The R13B03 release.OTP_R13B03

1 files changed, 141 insertions, 0 deletions

diff --git a/lib/erl_interface/doc/src/erl_global.xml b/lib/erl_interface/doc/src/erl_global.xml
new file mode 100644
index 0000000000..8f9a354b4f
--- /dev/null
+++ b/lib/erl_interface/doc/src/erl_global.xml
@@ -0,0 +1,141 @@
+<?xml version="1.0" encoding="latin1" ?>
+<!DOCTYPE cref SYSTEM "cref.dtd">
+
+<cref>
+  <header>
+    <copyright>
+      <year>1998</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>erl_global</title>
+    <prepared>Gordon Beaton</prepared>
+    <responsible>Gordon Beaton</responsible>
+    <docno></docno>
+    <approved>Gordon Beaton</approved>
+    <checked>Gordon Beaton</checked>
+    <date>980703</date>
+    <rev>A</rev>
+    <file>erl_global.sgml</file>
+  </header>
+  <lib>erl_global</lib>
+  <libsummary>Access globally registered names</libsummary>
+  <description>
+    <p>This module provides support for registering, looking
+      up and unregistering names in the Erlang Global module. For more
+      information, see the description of Global in the reference manual.</p>
+    <p>Note that the functions below perform an RPC using an open file
+      descriptor provided by the caller. This file descriptor must 
+      not be used for other traffic during the global operation or the 
+      function may receive unexpected data and fail.</p>
+  </description>
+  <funcs>
+    <func>
+      <name><ret>char **</ret><nametext>erl_global_names(fd,count)</nametext></name>
+      <fsummary>Obtain list of Global names</fsummary>
+      <type>
+        <v>int fd;</v>
+        <v>int *count;</v>
+      </type>
+      <desc>
+        <p>Retrieve a list of all known global names.
+          </p>
+        <p><c><![CDATA[fd]]></c> is an open descriptor to an Erlang connection.
+          </p>
+        <p><c><![CDATA[count]]></c> is the address of an integer, or NULL. If
+          <c><![CDATA[count]]></c> is not NULL, it will be set by the function to
+          the number of names found.
+          </p>
+        <p>On success, the function returns an array of strings, each
+          containing a single registered name, and sets <c><![CDATA[count]]></c> to
+          the number of names found. The array is terminated
+          by a single NULL pointer. On failure, the function returns
+          NULL and <c><![CDATA[count]]></c> is not modified.
+          </p>
+        <note>
+          <p>It is the caller's responsibility to free the array
+            afterwards. It has been allocated by the function with a
+            single call to <c><![CDATA[malloc()]]></c>, so a single <c><![CDATA[free()]]></c> is
+            all that is necessary.</p>
+        </note>
+      </desc>
+    </func>
+    <func>
+      <name><ret>int</ret><nametext>erl_global_register(fd,name,pid)</nametext></name>
+      <fsummary>Register a name in Global</fsummary>
+      <type>
+        <v>int fd;</v>
+        <v>const char *name;</v>
+        <v>ETERM *pid;</v>
+      </type>
+      <desc>
+        <p>This function registers a name in Global.
+          </p>
+        <p><c><![CDATA[fd]]></c> is an open descriptor to an Erlang connection.
+          </p>
+        <p><c><![CDATA[name]]></c> is the name to register in Global.
+          </p>
+        <p><c><![CDATA[pid]]></c> is the pid that should be associated with
+          <c><![CDATA[name]]></c>. This is the value that Global will return when
+          processes request the location of <c><![CDATA[name]]></c>.
+          </p>
+        <p>The function returns 0 on success, or -1 on failure.</p>
+      </desc>
+    </func>
+    <func>
+      <name><ret>int</ret><nametext>erl_global_unregister(fd,name)</nametext></name>
+      <fsummary>Unregister a name in Global</fsummary>
+      <type>
+        <v>int fd;</v>
+        <v>const char *name;</v>
+      </type>
+      <desc>
+        <p>This function unregisters a name from Global.
+          </p>
+        <p><c><![CDATA[fd]]></c> is an open descriptor to an Erlang connection.
+          </p>
+        <p><c><![CDATA[name]]></c> is the name to unregister from Global.
+          </p>
+        <p>The function returns 0 on success, or -1 on failure.</p>
+      </desc>
+    </func>
+    <func>
+      <name><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>
+        <v>const char *name;</v>
+        <v>char *node;</v>
+      </type>
+      <desc>
+        <p><c><![CDATA[fd]]></c> is an open descriptor to an Erlang connection.
+          </p>
+        <p><c><![CDATA[name]]></c> is the name that is to be looked up in Global.
+          </p>
+        <p>If <c><![CDATA[node]]></c> is not NULL, it is a pointer to a buffer
+          where the function can fill in the name of the node where
+          <c><![CDATA[name]]></c> is found. <c><![CDATA[node]]></c> can be passed directly to
+          <c><![CDATA[erl_connect()]]></c> if necessary.
+          </p>
+        <p>On success, the function returns an Erlang Pid containing the address
+          of the given name, and node will be initialized to
+          the nodename where <c><![CDATA[name]]></c> is found. On failure NULL will be
+          returned and <c><![CDATA[node]]></c> will not be modified.</p>
+      </desc>
+    </func>
+  </funcs>
+</cref>
+