The R13B03 release.OTP_R13B03

1 files changed, 246 insertions, 0 deletions

diff --git a/lib/ic/doc/src/ic_clib.xml b/lib/ic/doc/src/ic_clib.xml
new file mode 100644
index 0000000000..b557c4b5f6
--- /dev/null
+++ b/lib/ic/doc/src/ic_clib.xml
@@ -0,0 +1,246 @@
+<?xml version="1.0" encoding="latin1" ?>
+<!DOCTYPE cref SYSTEM "cref.dtd">
+
+<cref>
+  <header>
+    <copyright>
+      <year>2003</year><year>2009</year>
+      <holder>Ericsson AB. All Rights Reserved.</holder>
+    </copyright>
+    <legalnotice>
+      The contents of this file are subject to the Erlang Public License,
+      Version 1.1, (the "License"); you may not use this file except in
+      compliance with the License. You should have received a copy of the
+      Erlang Public License along with this software. If not, it can be
+      retrieved online at http://www.erlang.org/.
+    
+      Software distributed under the License is distributed on an "AS IS"
+      basis, WITHOUT WARRANTY OF ANY KIND, either express or implied. See
+      the License for the specific language governing rights and limitations
+      under the License.
+    
+    </legalnotice>
+
+    <title>IC C Library Functions</title>
+    <prepared></prepared>
+    <docno></docno>
+    <date>2003-12-16</date>
+    <rev>PB1</rev>
+  </header>
+  <lib>ic_clib</lib>
+  <libsummary>IC C Library Functions</libsummary>
+  <description>
+    <p>This manual page lists some of the functions in the IC C runtime
+      library. </p>
+  </description>
+
+  <section>
+    <title>Allocation and Deallocation Functions</title>
+    <p>The following functions are used for allocating and
+      deallocating a <em>CORBA_Environment</em> structure.</p>
+  </section>
+  <funcs>
+    <func>
+      <name><ret>CORBA_Environment*</ret><nametext>CORBA_Environment_alloc(int inbufsz, int outbufsz)</nametext></name>
+      <fsummary>Allocate environment data.</fsummary>
+      <desc>
+        <p>This function is used to allocate and initiate the
+          <c>CORBA_Environment</c> structure. In particular, it is used
+          to dynamically allocate a CORBA_Environment structure and set
+          the default values for the structure's fields.</p>
+        <p><em>inbufsize</em> is the initial size of the input
+          buffer.</p>
+        <p><em>outbufsize</em> is the initial size of the output
+          buffer.</p>
+        <p><em>CORBA_Environment</em> is the CORBA 2.0 state structure
+          used by the generated stub.</p>
+        <p>This function will set all needed default values and
+          allocate buffers the lengths of which are equal to the
+          values passed, but will not allocate space for the _to_pid
+          and _from_pid fields.</p>
+        <p>To free the space allocated by CORBA_Environment_alloc() do
+          as follows.</p>
+        <list type="bulleted">
+          <item>
+            <p>First call CORBA_free for the input and output buffers.</p>
+          </item>
+          <item>
+            <p>After freeing the buffer space, call CORBA_free for the
+              CORBA_Environment space.</p>
+          </item>
+        </list>
+      </desc>
+    </func>
+    <func>
+      <name><ret>void</ret><nametext>CORBA_free(void *p)</nametext></name>
+      <fsummary>Free any allocated data.</fsummary>
+      <desc>
+        <p>Frees allocated space pointed to by <c>p</c>.</p>
+      </desc>
+    </func>
+    <func>
+      <name><ret>CORBA_char*</ret><nametext>CORBA_string_alloc(CORBA_unsigned_long len)</nametext></name>
+      <fsummary>Allocate a string.</fsummary>
+      <desc>
+        <p>Allocates a (simple) CORBA character string of length <c>len + 1</c>.</p>
+      </desc>
+    </func>
+    <func>
+      <name><ret>CORBA_wchar*</ret><nametext>CORBA_wstring_alloc(CORBA_unsigned_long len)</nametext></name>
+      <fsummary>Allocate a wide string.</fsummary>
+      <desc>
+        <p>Allocates a CORBA wide string of length <c>len + 1</c>.</p>
+      </desc>
+    </func>
+  </funcs>
+
+  <section>
+    <title>Exception Functions</title>
+    <p>Functions for retrieving exception ids and values, and for setting
+      exceptions. </p>
+  </section>
+  <funcs>
+    <func>
+      <name><ret>CORBA_char*</ret><nametext>CORBA_exception_id(CORBA_Environment *env)</nametext></name>
+      <fsummary>Get exception identity.</fsummary>
+      <desc>
+        <p>Returns the exception identity if an exception is set, otherwise
+          it returns <c>NULL</c>.</p>
+      </desc>
+    </func>
+    <func>
+      <name><ret>void*</ret><nametext>CORBA_exception_value(CORBA_Environment *env)</nametext></name>
+      <fsummary>Get exception value.</fsummary>
+      <desc>
+        <p>Returns the exception value, if an exception is set, otherwise
+          it returns <c>NULL</c>.</p>
+      </desc>
+    </func>
+    <func>
+      <name><ret>void</ret><nametext>CORBA_exc_set(CORBA_Environment *env, CORBA_exception_type Major, CORBA_char *Id, CORBA_char *Value)</nametext></name>
+      <fsummary>Set exception.</fsummary>
+      <desc>
+        <p>Sets the exception type, exception identity, and exception value
+          in the environment pointed to by <c>env</c>.</p>
+      </desc>
+    </func>
+  </funcs>
+
+  <section>
+    <title>Server Reception</title>
+    <p>The following function is provided for convenience. </p>
+  </section>
+  <funcs>
+    <func>
+      <name><ret>int</ret><nametext>oe_server_receive(CORBA_Environment *env, oe_map_t *map)</nametext></name>
+      <name><ret>int</ret><nametext>oe_server_receive_tmo(CORBA_Environment *env, oe_map_t *map,  unsigned int send_ms, unsigned int recv_ms)</nametext></name>
+      <fsummary>Server receive of notification or request, and sending of reply (in case of request).</fsummary>
+      <desc>
+        <p>Provides a loop that receives one message, executes the
+          operation in question, and in case of a two-way operation
+          sends a reply.</p>
+        <p><c>send_ms</c> and <c>recv_ms</c> specify timeout values
+          in milliseconds for send and receive, respectively.</p>
+      </desc>
+    </func>
+  </funcs>
+
+  <section>
+    <title>Generic Execution Switch and Map Merging</title>
+    <p>Function for searching for server operation function, and for
+      calling it if found. Function for merging maps (see the include
+      file <c>ic.h</c> for definitions). </p>
+  </section>
+  <funcs>
+    <func>
+      <name><ret>int</ret><nametext>oe_exec_switch(CORBA_Object obj, CORBA_Environment *env, oe_map_t *map)</nametext></name>
+      <fsummary>Search for server operation and execute it.</fsummary>
+      <desc>
+        <p>Search for server operation and execute it.</p>
+      </desc>
+    </func>
+    <func>
+      <name><ret>oe_map_t*</ret><nametext>oe_merge_maps(oe_map_t *maps, int size)</nametext></name>
+      <fsummary>Merge an array of server maps to one single map.</fsummary>
+      <desc>
+        <p>Merge an array of server maps to one single map.</p>
+      </desc>
+    </func>
+  </funcs>
+
+  <section>
+    <title>The CORBA_Environment structure</title>
+    <p>Here is the complete definition of the CORBA_Environment structure,
+      defined in file <em>ic.h</em>: </p>
+    <code type="none">
+      /* Environment definition */
+      typedef struct {
+
+      /*----- CORBA compatibility part ------------------------*/
+      /* Exception tag, initially set to CORBA_NO_EXCEPTION ---*/
+      CORBA_exception_type   _major;          
+
+      /*----- External Implementation part - initiated by the user ---*/
+      /* File descriptor                                              */
+      int                    _fd;             
+      /* Size of input buffer                                         */
+      int                    _inbufsz;        
+      /* Pointer to always dynamically allocated buffer for input     */
+      char                  *_inbuf;         
+      /* Size of output buffer                                        */
+      int                    _outbufsz;       
+      /* Pointer to always dynamically allocated buffer for output    */ 
+      char                  *_outbuf;        
+      /* Size of memory chunks in bytes, used for increasing the output
+      buffer, set to >= 32, should be around >= 1024 for performance
+      reasons                                                       */ 
+      int                    _memchunk;       
+      /* Pointer for registered name                                   */
+      char                   _regname[256];   
+      /* Process identity for caller                                   */
+      erlang_pid            *_to_pid;         
+      /* Process identity for callee                                  */ 
+      erlang_pid            *_from_pid;      
+
+      /*- Internal Implementation part - used by the server/client ---*/
+      /* Index for input buffer                                       */
+      int                    _iin;            
+      /* Index for output buffer                                      */
+      int                    _iout;          
+      /* Pointer for operation name                                   */
+      char                   _operation[256];
+      /* Used to count parameters                                    */
+      int                    _received;      
+      /* Used to identify the caller                                  */
+      erlang_pid             _caller;        
+      /* Used to identify the call                                     */
+      erlang_ref             _unique;         
+      /* Exception id field                                           */
+      CORBA_char            *_exc_id;        
+      /* Exception value field                                        */
+      void                  *_exc_value;           
+
+      
+      } CORBA_Environment; 
+    </code>
+    <note>
+      <p>Always set the field values <em>_fd</em>, <em>_regname</em>,
+        <em>_to_pid</em> and/or <em>*_from_pid</em> to appropriate
+        application values. These are not automatically set by the
+        stubs.</p>
+    </note>
+    <warning>
+      <p>Never assign static buffers to the buffer pointers, and never
+        set the <em>_memchunk</em> field to a value less than
+        <em>32</em>.</p>
+    </warning>
+  </section>
+
+  <section>
+    <title>SEE ALSO</title>
+    <p>ic(3), ic_c_protocol(3)
+      </p>
+  </section>
+  
+</cref>
+