aboutsummaryrefslogtreecommitdiffstats
path: root/erts/doc/src
diff options
context:
space:
mode:
Diffstat (limited to 'erts/doc/src')
-rw-r--r--erts/doc/src/Makefile47
-rw-r--r--erts/doc/src/alt_dist.xml12
-rw-r--r--erts/doc/src/driver.xml50
-rw-r--r--erts/doc/src/driver_entry.xml32
-rw-r--r--erts/doc/src/epmd.xml271
-rw-r--r--erts/doc/src/erl.xml182
-rw-r--r--erts/doc/src/erl_dist_protocol.xml4
-rw-r--r--erts/doc/src/erl_driver.xml98
-rw-r--r--erts/doc/src/erl_ext_dist.xml2
-rw-r--r--erts/doc/src/erl_nif.xml565
-rw-r--r--erts/doc/src/erl_prim_loader.xml88
-rw-r--r--erts/doc/src/erlang.xml1071
-rw-r--r--erts/doc/src/erlc.xml46
-rw-r--r--erts/doc/src/erlsrv.xml19
-rw-r--r--erts/doc/src/erts_alloc.xml94
-rw-r--r--erts/doc/src/escript.xml227
-rw-r--r--erts/doc/src/init.xml82
-rw-r--r--erts/doc/src/match_spec.xml54
-rw-r--r--erts/doc/src/notes.xml2265
-rw-r--r--erts/doc/src/run_erl.xml10
-rw-r--r--erts/doc/src/specs.xml7
-rw-r--r--erts/doc/src/start_erl.xml31
-rw-r--r--erts/doc/src/zlib.xml363
23 files changed, 4414 insertions, 1206 deletions
diff --git a/erts/doc/src/Makefile b/erts/doc/src/Makefile
index 3dfefa2001..cfa5527474 100644
--- a/erts/doc/src/Makefile
+++ b/erts/doc/src/Makefile
@@ -1,21 +1,24 @@
#
# %CopyrightBegin%
-#
-# Copyright Ericsson AB 1997-2009. All Rights Reserved.
-#
+#
+# Copyright Ericsson AB 1997-2011. All Rights Reserved.
+#
# 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.
-#
+#
# %CopyrightEnd%
#
+
+SPECS_ESRC = ../../preloaded/src/
+
include $(ERL_TOP)/make/target.mk
include $(ERL_TOP)/make/$(TARGET)/otp.mk
@@ -43,8 +46,15 @@ XML_REF1_FILES = epmd.xml \
run_erl.xml \
start.xml
+XML_REF3_EFILES = \
+ erl_prim_loader.xml \
+ erlang.xml \
+ init.xml \
+ zlib.xml
+
XML_REF3_FILES = \
driver_entry.xml \
+ erl_nif.xml \
erl_set_memory_block.xml \
erl_driver.xml \
erl_prim_loader.xml \
@@ -97,18 +107,26 @@ HTML_REF_MAN_FILE = $(HTMLDIR)/index.html
TOP_PDF_FILE = $(PDFDIR)/$(APPLICATION)-$(VSN).pdf
+SPECS_FILES = $(XML_REF3_EFILES:%.xml=$(SPECDIR)/specs_%.xml)
+
+TOP_SPECS_FILE = specs.xml
+
# ----------------------------------------------------
# FLAGS
# ----------------------------------------------------
XML_FLAGS +=
+KERNEL_SRC=$(ERL_TOP)/lib/kernel/src
+KERNEL_INCLUDE=$(ERL_TOP)/lib/kernel/include
+SPECS_FLAGS = -I$(KERNEL_SRC) -I$(KERNEL_INCLUDE)
+
# ----------------------------------------------------
# Targets
# ----------------------------------------------------
$(HTMLDIR)/%.gif: %.gif
$(INSTALL_DATA) $< $@
-docs: pdf html man $(INFO_FILE)
+docs: man pdf html $(INFO_FILE)
$(TOP_PDF_FILE): $(XML_FILES)
@@ -131,8 +149,25 @@ clean:
rm -f $(MAN1DIR)/*
rm -f $(MAN3DIR)/*
rm -f $(TOP_PDF_FILE) $(TOP_PDF_FILE:%.pdf=%.fo)
+ rm -f $(SPECDIR)/*
rm -f errs core *~
+$(SPECDIR)/specs_driver_entry.xml:
+ escript $(SPECS_EXTRACTOR) $(SPECS_FLAGS) \
+ -o$(dir $@) -module driver_entry
+$(SPECDIR)/specs_erl_nif.xml:
+ escript $(SPECS_EXTRACTOR) $(SPECS_FLAGS) \
+ -o$(dir $@) -module erl_nif
+$(SPECDIR)/specs_erl_set_memory_block.xml:
+ escript $(SPECS_EXTRACTOR) $(SPECS_FLAGS) \
+ -o$(dir $@) -module erl_set_memory_block
+$(SPECDIR)/specs_erl_driver.xml:
+ escript $(SPECS_EXTRACTOR) $(SPECS_FLAGS) \
+ -o$(dir $@) -module erl_driver
+$(SPECDIR)/specs_erts_alloc.xml:
+ escript $(SPECS_EXTRACTOR) $(SPECS_FLAGS) \
+ -o$(dir $@) -module erts_alloc
+
# ----------------------------------------------------
# Release Target
# ----------------------------------------------------
diff --git a/erts/doc/src/alt_dist.xml b/erts/doc/src/alt_dist.xml
index a929aec97f..038950b54d 100644
--- a/erts/doc/src/alt_dist.xml
+++ b/erts/doc/src/alt_dist.xml
@@ -4,7 +4,7 @@
<chapter>
<header>
<copyright>
- <year>2000</year><year>2010</year>
+ <year>2000</year><year>2011</year>
<holder>Ericsson AB. All Rights Reserved.</holder>
</copyright>
<legalnotice>
@@ -377,7 +377,7 @@
( 1) typedef enum {
( 2) portTypeUnknown, /* An uninitialized port */
( 3) portTypeListener, /* A listening port/socket */
-( 4) portTypeAcceptor, /* An intermidiate stage when accepting
+( 4) portTypeAcceptor, /* An intermediate stage when accepting
( 5) on a listen port */
( 6) portTypeConnector, /* An intermediate stage when connecting */
( 7) portTypeCommand, /* A connected open port in command mode */
@@ -434,7 +434,7 @@
(13) Word received; /* Bytes received */
(14) struct uds_data *partner; /* The partner in an accept/listen pair */
(15) struct uds_data *next; /* Next structure in list */
-(16) /* The input buffer and it's data */
+(16) /* The input buffer and its data */
(17) int buffer_size; /* The allocated size of the input buffer */
(18) int buffer_pos; /* Current position in input buffer */
(19) int header_pos; /* Where the current header is in the
@@ -825,7 +825,7 @@
I/O vector itself. One can use this to allocate the binaries
for the queue "manually" in the driver, but we'll just fill
the binary array with NULL values (line 7) , which will make
- the runtime system allocate it's own buffers when we call
+ the runtime system allocate its own buffers when we call
<c><![CDATA[driver_enqv]]></c> (line 37).</p>
<p></p>
<p>The routine builds an I/O vector containing the header bytes
@@ -942,7 +942,7 @@
between invocations of Erlang nodes with the same name.</item>
</list>
<p>The control interface gets a buffer to return its value in,
- but is free to allocate it's own buffer is the provided one is
+ but is free to allocate its own buffer is the provided one is
to small. Here is the code for <c><![CDATA[uds_control]]></c>:</p>
<code type="none"><![CDATA[
( 1) static int uds_control(ErlDrvData handle, unsigned int command,
@@ -1042,7 +1042,7 @@
<c><![CDATA[net_kernel:start/1]]></c> function, which is useful as it starts
the distribution on a running system, where tracing/debugging
can be performed. The <c><![CDATA[net_kernel:start/1]]></c> routine takes a
- list as it's single argument. The lists first element should be
+ list as its single argument. The lists first element should be
the node name (without the "@hostname") as an atom, and the second (and
last) element should be one of the atoms <c><![CDATA[shortnames]]></c> or
<c><![CDATA[longnames]]></c>. In the example case <c><![CDATA[shortnames]]></c> is
diff --git a/erts/doc/src/driver.xml b/erts/doc/src/driver.xml
index 12c79aee90..9f246c4a6c 100644
--- a/erts/doc/src/driver.xml
+++ b/erts/doc/src/driver.xml
@@ -4,7 +4,7 @@
<chapter>
<header>
<copyright>
- <year>2001</year><year>2010</year>
+ <year>2001</year><year>2011</year>
<holder>Ericsson AB. All Rights Reserved.</holder>
</copyright>
<legalnotice>
@@ -63,7 +63,8 @@
<p>This is a simple driver for accessing a postgres
database using the libpq C client library. Postgres
is used because it's free and open source. For information
- on postgres, refer to the website www.postgres.org.</p>
+ on postgres, refer to the website
+ <url href="http://www.postgres.org">www.postgres.org</url>.</p>
<p>The driver is synchronous, it uses the synchronous calls of
the client library. This is only for simplicity, and is
generally not good, since it will
@@ -196,18 +197,21 @@ static ErlDrvData start(ErlDrvPort port, char *command)
<p>We call disconnect to log out from the database.
(This should have been done from Erlang, but just in case.)</p>
<code type="none"><![CDATA[
- static int do_disconnect(our_data_t* data, ei_x_buff* x);
+static int do_disconnect(our_data_t* data, ei_x_buff* x);
static void stop(ErlDrvData drv_data)
{
- do_disconnect((our_data_t*)drv_data, NULL);
+ our_data_t* data = (our_data_t*)drv_data;
+
+ do_disconnect(data, NULL);
+ driver_free(data);
}
]]></code>
<p>We use the binary format only to return data to the emulator;
input data is a string paramater for <c><![CDATA[connect]]></c> and
<c><![CDATA[select]]></c>. The returned data consists of Erlang terms.</p>
<p>The functions <c><![CDATA[get_s]]></c> and <c><![CDATA[ei_x_to_new_binary]]></c> are
- utilities that is used to make the code shorter. <c><![CDATA[get_s]]></c>
+ utilities that are used to make the code shorter. <c><![CDATA[get_s]]></c>
duplicates the string and zero-terminates it, since the
postgres client library wants that. <c><![CDATA[ei_x_to_new_binary]]></c>
takes an <c><![CDATA[ei_x_buff]]></c> buffer and allocates a binary and
@@ -241,7 +245,7 @@ static int control(ErlDrvData drv_data, unsigned int command, char *buf,
return r;
}
]]></code>
- <p>In <c><![CDATA[do_connect]]></c> is where we log in to the database. If the connection
+ <p><c><![CDATA[do_connect]]></c> is where we log in to the database. If the connection
was successful we store the connection handle in our driver
data, and return ok. Otherwise, we return the error message
from postgres, and store <c><![CDATA[NULL]]></c> in the driver data.</p>
@@ -261,7 +265,7 @@ static int do_connect(const char *s, our_data_t* data, ei_x_buff* x)
}
]]></code>
<p>If we are connected (if the connection handle is not <c><![CDATA[NULL]]></c>),
- we log out from the database. We need to check if a we should
+ we log out from the database. We need to check if we should
encode an ok, since we might get here from the <c><![CDATA[stop]]></c>
function, which doesn't return data to the emulator.</p>
<code type="none"><![CDATA[
@@ -276,7 +280,7 @@ static int do_disconnect(our_data_t* data, ei_x_buff* x)
return 0;
}
]]></code>
- <p>We execute a query and encodes the result. Encoding is done
+ <p>We execute a query and encode the result. Encoding is done
in another C module, <c><![CDATA[pg_encode.c]]></c> which is also provided
as sample code.</p>
<code type="none"><![CDATA[
@@ -288,7 +292,7 @@ static int do_select(const char* s, our_data_t* data, ei_x_buff* x)
return 0;
}
]]></code>
- <p>Here we simply checks the result from postgres, and
+ <p>Here we simply check the result from postgres, and
if it's data we encode it as lists of lists with
column data. Everything from postgres is C strings,
so we just use <c><![CDATA[ei_x_encode_string]]></c> to send
@@ -389,7 +393,7 @@ disconnect(Port) ->
select(Port, Query) ->
binary_to_term(port_control(Port, ?DRV_SELECT, Query)).
]]></code>
- <p>The api is simple: <c><![CDATA[connect/1]]></c> loads the driver, opens it
+ <p>The API is simple: <c><![CDATA[connect/1]]></c> loads the driver, opens it
and logs on to the database, returning the Erlang port
if successful, <c><![CDATA[select/2]]></c> sends a query to the driver,
and returns the result, <c><![CDATA[disconnect/1]]></c> closes the
@@ -413,8 +417,8 @@ select(Port, Query) ->
<title>Sample asynchronous driver</title>
<p>Sometimes database queries can take long time to
complete, in our <c><![CDATA[pg_sync]]></c> driver, the emulator
- halts while the driver is doing it's job. This is
- often not acceptable, since no other Erlang processes
+ halts while the driver is doing its job. This is
+ often not acceptable, since no other Erlang process
gets a chance to do anything. To improve on our
postgres driver, we reimplement it using the asynchronous
calls in LibPQ.</p>
@@ -469,7 +473,7 @@ typedef struct our_data_t {
whether the driver is waiting for a connection or waiting
for the result of a query. (This is needed since the entry
<c><![CDATA[ready_io]]></c> will be called both when connecting and
- when there is query result.)</p>
+ when there is a query result.)</p>
<code type="none"><![CDATA[
static int do_connect(const char *s, our_data_t* data)
{
@@ -568,7 +572,7 @@ static void ready_io(ErlDrvData drv_data, ErlDrvEvent event)
connection is successful, or error if it's not. If the
connection is not yet established, we simply return; <c><![CDATA[ready_io]]></c>
will be called again.</p>
- <p>If we have result from a connect, indicated that we have data in
+ <p>If we have a result from a connect, indicated by having data in
the <c><![CDATA[x]]></c> buffer, we no longer need to select on
output (<c><![CDATA[ready_output]]></c>), so we remove this by calling
<c><![CDATA[driver_select]]></c>.</p>
@@ -627,9 +631,9 @@ return_port_data(Port) ->
message queue. The function <c><![CDATA[return_port_data]]></c> above
receives data from the port. Since the data is in
binary format, we use <c><![CDATA[binary_to_term/1]]></c> to convert
- it to Erlang term. Note that the driver is opened in
- binary mode, <c><![CDATA[open_port/2]]></c> is called with the option
- <c><![CDATA[[binary]]]></c>. This means that data sent from the driver
+ it to an Erlang term. Note that the driver is opened in
+ binary mode (<c><![CDATA[open_port/2]]></c> is called with the option
+ <c><![CDATA[[binary]]]></c>). This means that data sent from the driver
to the emulator is sent as binaries. Without the <c><![CDATA[binary]]></c>
option, they would have been lists of integers.</p>
</section>
@@ -643,15 +647,15 @@ return_port_data(Port) ->
of a list of integers. For large lists (more than 100000
elements), this will take some time, so we will perform this
as an asynchronous task.</p>
- <p>The asynchronous api for drivers are quite complicated. First
+ <p>The asynchronous API for drivers is quite complicated. First
of all, the work must be prepared. In our example we do this
in <c><![CDATA[output]]></c>. We could have used <c><![CDATA[control]]></c> just as well,
but we want some variation in our examples. In our driver, we allocate
- a structure that contains all needed for the asynchronous task
+ a structure that contains anything that's needed for the asynchronous task
to do the work. This is done in the main emulator thread.
Then the asynchronous function is called from a driver thread,
- separate from the main emulator thread. Note that the driver-
- functions are not reentrant, so they shouldn't be used.
+ separate from the main emulator thread. Note that the driver-functions
+ are not reentrant, so they shouldn't be used.
Finally, after the function is completed, the driver callback
<c><![CDATA[ready_async]]></c> is called from the main emulator thread,
this is where we return the result to Erlang. (We can't
@@ -689,7 +693,7 @@ static ErlDrvEntry next_perm_driver_entry = {
be sent later from the <c><![CDATA[ready_async]]></c> call-back.</p>
<p>The <c><![CDATA[async_data]]></c> will be passed to the <c><![CDATA[do_perm]]></c> function.
We do not use a <c><![CDATA[async_free]]></c> function (the last argument to
- <c><![CDATA[driver_async]]></c>, it's only used if the task is cancelled
+ <c><![CDATA[driver_async]]></c>), it's only used if the task is cancelled
programmatically.</p>
<code type="none"><![CDATA[
struct our_async_data {
@@ -740,7 +744,7 @@ static void ready_async(ErlDrvData drv_data, ErlDrvThreadData async_data)
ErlDrvPort port = reinterpret_cast<ErlDrvPort>(drv_data);
our_async_data* d = reinterpret_cast<our_async_data*>(async_data);
int n = d->data.size(), result_n = n*2 + 3;
- ErlDrvTermData* result = new ErlDrvTermData[result_n], * rp = result;
+ ErlDrvTermData *result = new ErlDrvTermData[result_n], *rp = result;
for (vector<int>::iterator i = d->data.begin();
i != d->data.end(); ++i) {
*rp++ = ERL_DRV_INT;
diff --git a/erts/doc/src/driver_entry.xml b/erts/doc/src/driver_entry.xml
index e71b48bd92..8bdd154cb9 100644
--- a/erts/doc/src/driver_entry.xml
+++ b/erts/doc/src/driver_entry.xml
@@ -4,7 +4,7 @@
<cref>
<header>
<copyright>
- <year>2001</year><year>2010</year>
+ <year>2001</year><year>2011</year>
<holder>Ericsson AB. All Rights Reserved.</holder>
</copyright>
<legalnotice>
@@ -36,7 +36,7 @@
<description>
<p>As of erts version 5.5.3 the driver interface has been extended
(see <seealso marker="driver_entry#extended_marker">extended marker</seealso>).
- The extended interface introduce
+ The extended interface introduces
<seealso marker="erl_driver#version_management">version management</seealso>,
the possibility to pass capability flags
(see <seealso marker="driver_entry#driver_flags">driver flags</seealso>)
@@ -45,21 +45,21 @@
<note>
<p>Old drivers (compiled with an <c>erl_driver.h</c> from an
earlier erts version than 5.5.3) have to be recompiled
- (but does not have to use the extended interface).</p>
+ (but do not have to use the extended interface).</p>
</note>
<p>The <c>driver_entry</c> structure is a C struct that all erlang
- drivers defines. It contains entry points for the erlang driver
+ drivers define. It contains entry points for the erlang driver
that are called by the erlang emulator when erlang code accesses
the driver.</p>
<p>
<marker id="emulator"></marker>
The <seealso marker="driver_entry">erl_driver</seealso> driver
- API functions needs a port handle
+ API functions need a port handle
that identifies the driver instance (and the port in the
emulator). This is only passed to the <c>start</c> function, but
not to the other functions. The <c>start</c> function returns a
driver-defined handle that is passed to the other functions. A
- common practice is to have the <c>start</c> function allocating
+ common practice is to have the <c>start</c> function allocate
some application-defined structure and stash the <c>port</c>
handle in it, to use it later with the driver API functions.</p>
<p>The driver call-back functions are called synchronously from the
@@ -121,7 +121,7 @@ typedef struct erl_drv_entry {
the port */
void (*ready_input)(ErlDrvData drv_data, ErlDrvEvent event);
/* called when we have input from one of
- the driver's handles) */
+ the driver's handles */
void (*ready_output)(ErlDrvData drv_data, ErlDrvEvent event);
/* called when output is possible to one of
the driver's handles */
@@ -133,7 +133,7 @@ typedef struct erl_drv_entry {
int (*control)(ErlDrvData drv_data, unsigned int command, char *buf,
int len, char **rbuf, int rlen);
/* "ioctl" for drivers - invoked by
- port_control/3) */
+ port_control/3 */
void (*timeout)(ErlDrvData drv_data); /* Handling of timeout in driver */
void (*outputv)(ErlDrvData drv_data, ErlIOVec *ev);
/* called when we have output from erlang
@@ -146,7 +146,7 @@ typedef struct erl_drv_entry {
before 'stop' can be called */
int (*call)(ErlDrvData drv_data, unsigned int command, char *buf,
int len, char **rbuf, int rlen, unsigned int *flags);
- /* Works mostly like 'control', a syncronous
+ /* Works mostly like 'control', a synchronous
call into the driver. */
void (*event)(ErlDrvData drv_data, ErlDrvEvent event,
ErlDrvEventData event_data);
@@ -172,7 +172,7 @@ typedef struct erl_drv_entry {
added to the driver list.) The driver should return 0, or if
the driver can't initialize, -1.</p>
</item>
- <tag><marker id="start"/>int (*start)(ErlDrvPort port, char* command)</tag>
+ <tag><marker id="start"/>ErlDrvData (*start)(ErlDrvPort port, char* command)</tag>
<item>
<p>This is called when the driver is instantiated, when
<c>open_port/2</c> is called. The driver should return a
@@ -188,7 +188,9 @@ typedef struct erl_drv_entry {
<p>This is called when the port is closed, with
<c>port_close/1</c> or <c>Port ! {self(), close}</c>. Note
that terminating the port owner process also closes the
- port.</p>
+ port. If <c>drv_data</c> is a pointer to memory allocated in
+ <c>start</c>, then <c>stop</c> is the place to deallocate that
+ memory.</p>
</item>
<tag><marker id="output"/>void (*output)(ErlDrvData drv_data, char *buf, int len)</tag>
<item>
@@ -217,6 +219,10 @@ typedef struct erl_drv_entry {
completes, write to the pipe (use <c>SetEvent</c> on
Windows), this will make the emulator call
<c>ready_input</c> or <c>ready_output</c>.</p>
+ <p>Spurious events may happen. That is, calls to <c>ready_input</c>
+ or <c>ready_output</c> even though no real events are signaled. In
+ reality it should be rare (and OS dependant), but a robust driver
+ must nevertheless be able to handle such cases.</p>
</item>
<tag><marker id="driver_name"/>char *driver_name</tag>
<item>
@@ -233,7 +239,7 @@ typedef struct erl_drv_entry {
</item>
<tag>void *handle</tag>
<item>
- <p>This field is reserved for the emulators internal use. The
+ <p>This field is reserved for the emulator's internal use. The
emulator will modify this field; therefore, it is important
that the <c>driver_entry</c> isn't declared <c>const</c>.</p>
</item>
@@ -397,7 +403,7 @@ typedef struct erl_drv_entry {
<tag>void *handle2</tag>
<item>
<p>
- This field is reserved for the emulators internal use. The
+ This field is reserved for the emulator's internal use. The
emulator will modify this field; therefore, it is important
that the <c>driver_entry</c> isn't declared <c>const</c>.
</p>
diff --git a/erts/doc/src/epmd.xml b/erts/doc/src/epmd.xml
index 796ab3820b..3e7005410f 100644
--- a/erts/doc/src/epmd.xml
+++ b/erts/doc/src/epmd.xml
@@ -4,7 +4,7 @@
<comref>
<header>
<copyright>
- <year>1996</year><year>2009</year>
+ <year>1996</year><year>2011</year>
<holder>Ericsson AB. All Rights Reserved.</holder>
</copyright>
<legalnotice>
@@ -31,9 +31,23 @@
<rev>A</rev>
<file>epmd.xml</file>
</header>
+
<com>epmd</com>
- <comsummary>Erlang Port Mapper Daemon </comsummary>
+ <comsummary>
+ <p>Erlang Port Mapper Daemon</p>
+ <taglist>
+ <tag><c><![CDATA[epmd [-d|-debug] [DbgExtra...] [-port No] [-daemon] [-relaxed_command_check]]]></c></tag>
+ <item>
+ <p>Starts the port mapper daemon</p>
+ </item>
+ <tag><c><![CDATA[epmd [-d|-debug] [-port No] [-names|-kill|-stop Name]]]></c></tag>
+ <item>
+ <p>Communicates with a running port mapper daemon</p>
+ </item>
+ </taglist>
+ </comsummary>
<description>
+
<p>This daemon acts as a name server on all hosts involved in
distributed Erlang computations. When an Erlang node
starts, the node has a name and it obtains an address from the host
@@ -46,51 +60,193 @@
The job of the <c><![CDATA[epmd]]></c> daemon is to keep track of which
node name listens on which address. Hence, <c><![CDATA[epmd]]></c> map
symbolic node names to machine addresses.</p>
- <p>The daemon is started automatically by the Erlang start-up script.</p>
- <p>The program <c><![CDATA[epmd]]></c> can also be used for a variety of other
- purposes, for example checking the DNS (Domain Name System)
- configuration of a host.</p>
+
+ <p>The TCP/IP <c>epmd</c> daemon actually only keeps track of
+ the <c>Name</c> (first) part of an Erlang node name, the <c>Host</c>
+ part (whatever is after the <c><![CDATA[@]]></c> is implicit in the
+ node name where the <c>epmd</c> daemon was actually contacted,
+ as is the IP address where the Erlang node can be
+ reached. Consistent and correct TCP naming services are
+ therefore required for an Erlang network to function
+ correctly.</p>
+
+ <taglist>
+ <tag>Starting the port mapper daemon</tag>
+ <item>
+
+ <p>The daemon is started automatically by the <c>erl</c>
+ command if the node is to be distributed and there is no
+ running instance present. If automatically launched,
+ environment variables has to be used to alter the behavior of
+ the daemon. See the <seealso
+ marker="#environment_variables">Environment
+ variables</seealso> section below.</p>
+
+ <p>If the -daemon argument is not given, the
+ <c><![CDATA[epmd]]></c> runs as a normal program with the
+ controlling terminal of the shell in which it is
+ started. Normally, it should run as a daemon.</p>
+
+ <p>Regular start-up options are described in the
+ <seealso marker="#daemon_flags">Regular options</seealso>
+ section below.</p>
+
+ <p>The <c>DbgExtra</c> options are described in the
+ <seealso marker="#debug_flags">DbgExtra options</seealso>
+ section below.</p>
+
+ </item>
+ <tag>Communicating with a running port mapper daemon</tag>
+ <item>
+
+ <p>Communicating with the running epmd daemon by means of the
+ <c>epmd</c> program is done primarily for debugging
+ purposes.</p>
+
+ <p>The different queries are described in the <seealso
+ marker="#interactive_flags">Interactive options</seealso>
+ section below.</p>
+
+ </item>
+ </taglist>
</description>
- <funcs>
- <func>
- <name>epmd [-daemon] </name>
- <fsummary>Start a name server as a daemon</fsummary>
- <desc>
- <p>Starts a name server as a daemon. If it has no argument, the
- <c><![CDATA[epmd]]></c> runs as a normal program with the controlling terminal
- of the shell in which it is started. Normally, it should run as a
- daemon.</p>
- </desc>
- </func>
- <func>
- <name>epmd -names</name>
- <fsummary>Request the names of the registered Erlang nodes on this host</fsummary>
- <desc>
- <p>Requests the names of the local Erlang nodes <c><![CDATA[epmd]]></c> has
- registered.</p>
- </desc>
- </func>
- <func>
- <name>epmd -kill</name>
- <fsummary>Kill the <c><![CDATA[epmd]]></c>process</fsummary>
- <desc>
- <p>Kills the <c><![CDATA[epmd]]></c> process.</p>
- </desc>
- </func>
- <func>
- <name>epmd -help</name>
- <fsummary>List options</fsummary>
- <desc>
- <p>Write short info about the usage including some debugging
- options not listed here.</p>
- </desc>
- </func>
- </funcs>
+ <section>
+ <marker id="daemon_flags"></marker>
+ <title>Regular options</title>
+
+ <p>These options are available when starting the actual name server. The name server is normally started automatically by the <c>erl</c> command (if not already available), but it can also be started at i.e. system start-up.</p>
+ <taglist>
+ <tag><c><![CDATA[-address List]]></c></tag>
+ <item>
+ <p>Let this instance of <c>epmd</c> listen only on the
+ comma-separated list of IP addresses and on the loopback address
+ (which is implicitly added to the list if it has not been
+ specified). This can also be set using the
+ <c><![CDATA[ERL_EPMD_ADDRESS]]></c> environment variable, see the
+ section <seealso marker="#environment_variables">Environment
+ variables</seealso> below.</p>
+ </item>
+ <tag><c><![CDATA[-port No]]></c></tag>
+ <item>
+ <p>Let this instance of epmd listen to another TCP port than
+ default 4369. This can also be set using the
+ <c><![CDATA[ERL_EPMD_PORT]]></c> environment variable, see the
+ section <seealso marker="#environment_variables">Environment
+ variables</seealso> below</p>
+ </item>
+ <tag><c><![CDATA[-d | -debug]]></c></tag>
+ <item>
+
+ <p>Enable debug output. The more <c>-d</c> flags given, the more
+ debug output you will get (to a certain limit). This option is
+ most useful when the epmd daemon is not started as a daemon.</p>
+ </item>
+ <tag><c><![CDATA[-daemon]]></c></tag>
+ <item>
+ <p>Start epmd detached from the controlling terminal. Logging will end up in syslog when available and correctly configured. If the epmd daemon is started at boot, this option should definitely be used. It is also used when the <c>erl</c> command automatically starts <c>epmd</c>.</p>
+ </item>
+ <tag><c><![CDATA[-relaxed_command_check]]></c></tag>
+ <item>
+ <p>Start the epmd program with relaxed command checking (mostly for backward compatibility). This affects the following:</p>
+ <list type="bulleted">
+ <item>
+ <p>With relaxed command checking, the <c>epmd</c> daemon can be killed from the localhost with i.e. <c>epmd -kill</c> even if there are active nodes registered. Normally only daemons with an empty node database can be killed with the <c>epmd -kill</c> command.</p>
+ </item>
+ <item>
+ <p>The <c>epmd -stop</c> command (and the corresponding messages to epmd, as can be given using <c>erl_interface/ei</c>) is normally always ignored, as it opens up for strange situation when two nodes of the same name can be alive at the same time. A node unregisters itself by just closing the connection to epmd, why the <c>stop</c> command was only intended for use in debugging situations.</p>
+ <p>With relaxed command checking enabled, you can forcibly unregister live nodes.</p>
+ </item>
+ </list>
+ <p>Relaxed command checking can also be enabled by setting the environment variable <c>ERL_EPMD_RELAXED_COMMAND_CHECK</c> prior to starting <c>epmd</c>.</p>
+ <p>Only use relaxed command checking on systems with very limited interactive usage.</p>
+ </item>
+ </taglist>
+ </section>
<section>
+ <marker id="debug_flags"></marker>
+ <title>DbgExtra options</title>
+ <p>These options are purely for debugging and testing epmd clients, they should not be used in normal operation.</p>
+
+ <taglist>
+ <tag><c><![CDATA[-packet_timeout Seconds]]></c></tag>
+ <item>
+ <p>Set the number of seconds a connection can be
+ inactive before epmd times out and closes the
+ connection (default 60).</p>
+ </item>
+ <tag><c><![CDATA[-delay_accept Seconds]]></c></tag>
+ <item>
+ <p>To simulate a busy server you can insert a delay between epmd
+ gets notified about that a new connection is requested and
+ when the connections gets accepted.</p>
+ </item>
+ <tag><c><![CDATA[-delay_write Seconds]]></c></tag>
+ <item>
+ <p>Also a simulation of a busy server. Inserts
+ a delay before a reply is sent.</p>
+ </item>
+ </taglist>
+ </section>
+ <section>
+ <marker id="interactive_flags"></marker>
+ <title>Interactive options</title>
+ <p>These options make <c>epmd</c> run as an interactive command displaying the results of sending queries ta an already running instance of <c>epmd</c>. The epmd contacted is always on the local node, but the <c>-port</c> option can be used to select between instances if several are running using different port on the host.</p>
+ <taglist>
+ <tag><c><![CDATA[-port No]]></c></tag>
+ <item>
+ <p>Contacts the <c>epmd</c> listening on the given TCP port number
+ (default 4369). This can also be set using the
+ <c><![CDATA[ERL_EPMD_PORT]]></c> environment variable, see the
+ section <seealso marker="#environment_variables">Environment
+ variables</seealso> below</p>
+ </item>
+ <tag><c><![CDATA[-names]]></c></tag>
+ <item>
+ <p>List names registered with the currently running epmd</p>
+ </item>
+ <tag><c><![CDATA[-kill]]></c></tag>
+ <item>
+ <p>Kill the currently running <c>epmd</c>.</p>
+
+ <p>Killing the running <c>epmd</c> is only allowed if <c>epmd
+ -names</c> show an empty database or
+ <c>-relaxed_command_check</c> was given when the running
+ instance of <c>epmd</c> was started. Note that
+ <c>-relaxed_command_check</c> is given when starting the
+ daemon that is to accept killing when it has live nodes
+ registered. When running epmd interactively,
+ <c>-relaxed_command_check</c> has no effect. A daemon that is
+ started without relaxed command checking has to be killed
+ using i.e. signals or some other OS specific method if it has
+ active clients registered.</p>
+ </item>
+ <tag><c><![CDATA[-stop Name]]></c></tag>
+ <item>
+ <p>Forcibly unregister a live node from <c>epmd</c>'s database</p>
+
+ <p>This command can only be used when contacting <c>epmd</c>
+ instances started with the <c>-relaxed_command_check</c>
+ flag. Note that relaxed command checking has to be enabled for
+ the <c>epmd</c> daemon contacted, When running epmd
+ interactively,
+ <c>-relaxed_command_check</c> has no effect.</p>
+ </item>
+ </taglist>
+ </section>
+ <section>
<marker id="environment_variables"></marker>
<title>Environment variables</title>
<taglist>
+ <tag><c><![CDATA[ERL_EPMD_ADDRESS]]></c></tag>
+ <item>
+ <p>This environment variable may be set to a comma-separated
+ list of IP addresses, in which case the <c>epmd</c> daemon
+ will listen only on the specified address(es) and on the
+ loopback address (which is implicitly added to the list if it
+ has not been specified). The default behaviour is to listen on
+ all available IP addresses.</p>
+ </item>
<tag><c><![CDATA[ERL_EPMD_PORT]]></c></tag>
<item>
<p>This environment variable can contain the port number epmd will use.
@@ -99,6 +255,15 @@
independent clusters of nodes, to co-exist on the same host.
All nodes in a cluster must use the same epmd port number.</p>
</item>
+ <tag><c><![CDATA[ERL_EPMD_RELAXED_COMMAND_CHECK]]></c></tag>
+ <item>
+ <p>If set prior to start, the <c>epmd</c> daemon will behave
+ as if the <c>-relaxed_command_check</c> option was given at
+ start-up. If consequently setting this option before starting
+ the Erlang virtual machine, the automatically started
+ <c>epmd</c> will accept the <c>-kill</c> and <c>-stop</c>
+ commands without restrictions.</p>
+ </item>
</taglist>
</section>
@@ -116,5 +281,29 @@
silently be ignored.
</p>
</section>
+ <section>
+ <title>Access restrictions</title>
+ <p>The <c>epmd</c> daemon accepts messages from both localhost and
+ remote hosts. However, only the query commands are answered (and
+ acted upon) if the query comes from a remote host. It is always an
+ error to try to register a nodename if the client is not a process
+ located on the same host as the <c>epmd</c> instance is running on,
+ why such requests are considered hostile and the connection is
+ immediately closed.</p>
+
+ <p>The queries accepted from remote nodes are:</p>
+ <list type="bulleted">
+ <item>
+ <p>Port queries - i.e. on which port does the node with a given
+ name listen</p>
+ </item>
+ <item>
+ <p>Name listing - i.e. give a list of all names registered on
+ the host</p>
+ </item>
+ </list>
+ <p>To restrict access further, firewall software has to be used.</p>
+ </section>
+
</comref>
diff --git a/erts/doc/src/erl.xml b/erts/doc/src/erl.xml
index bb741c7836..02082e57c6 100644
--- a/erts/doc/src/erl.xml
+++ b/erts/doc/src/erl.xml
@@ -4,7 +4,7 @@
<comref>
<header>
<copyright>
- <year>1996</year><year>2010</year>
+ <year>1996</year><year>2011</year>
<holder>Ericsson AB. All Rights Reserved.</holder>
</copyright>
<legalnotice>
@@ -41,6 +41,26 @@
to scroll back to text which has scrolled off the screen.
The <c><![CDATA[erl]]></c> program must be used, however, in pipelines or if
you want to redirect standard input or output.</p>
+ <note><p>As of ERTS version 5.8 (OTP-R14A) the runtime system will by
+ default bind schedulers to logical processors using the
+ <c>default_bind</c> bind type if the amount of schedulers are
+ at least equal to the amount of logical processors configured,
+ binding of schedulers is supported, and a CPU topology is
+ available at startup.
+ </p><p>
+ If the Erlang runtime system is the only operating system
+ process that binds threads to logical processors, this
+ improves the performance of the runtime system. However,
+ if other operating system processes (as for example
+ another Erlang runtime system) also bind threads to
+ logical processors, there might be a performance penalty
+ instead. If this is the case you, are are advised to
+ unbind the schedulers using the
+ <seealso marker="#+sbt">+sbtu</seealso> command line argument,
+ or by invoking
+ <seealso marker="erlang#system_flag_scheduler_bind_type">erlang:system_flag(scheduler_bind_type,
+ unbound)</seealso>.</p>
+ </note>
</description>
<funcs>
<func>
@@ -211,7 +231,8 @@
<tag><c><![CDATA[-detached]]></c></tag>
<item>
<p>Starts the Erlang runtime system detached from the system
- console. Useful for running daemons and backgrounds processes.</p>
+ console. Useful for running daemons and backgrounds processes. Implies
+ <c><![CDATA[-noinput]]></c>.</p>
</item>
<tag><c><![CDATA[-emu_args]]></c></tag>
<item>
@@ -521,6 +542,28 @@
<p>Calling <c>erlang:halt/1</c> with a string argument will still
produce a crash dump.</p>
</item>
+ <tag><c><![CDATA[+e Number]]></c></tag>
+ <item>
+ <p>Set max number of ETS tables.</p>
+ </item>
+ <tag><c><![CDATA[+ec]]></c></tag>
+ <item>
+ <p>Force the <c>compressed</c> option on all ETS tables.
+ Only intended for test and evaluation.</p>
+ </item>
+ <tag><c><![CDATA[+fnl]]></c></tag>
+ <item>
+ <p>The VM works with file names as if they are encoded using the ISO-latin-1 encoding, disallowing Unicode characters with codepoints beyond 255. This is default on operating systems that have transparent file naming, i.e. all Unixes except MacOSX.</p>
+ </item>
+ <tag><c><![CDATA[+fnu]]></c></tag>
+ <item>
+ <p>The VM works with file names as if they are encoded using UTF-8 (or some other system specific Unicode encoding). This is the default on operating systems that enforce Unicode encoding, i.e. Windows and MacOSX.</p>
+ <p>By enabling Unicode file name translation on systems where this is not default, you open up to the possibility that some file names can not be interpreted by the VM and therefore will be returned to the program as raw binaries. The option is therefore considered experimental.</p>
+ </item>
+ <tag><c><![CDATA[+fna]]></c></tag>
+ <item>
+ <p>Selection between <c>+fnl</c> and <c>+fnu</c> is done based on the current locale settings in the OS, meaning that if you have set your terminal for UTF-8 encoding, the filesystem is expected to use the same encoding for filenames (use with care).</p>
+ </item>
<tag><c><![CDATA[+hms Size]]></c></tag>
<item>
<p>Sets the default heap size of processes to the size
@@ -583,6 +626,24 @@
<item>
<p>Force ets memory block to be moved on realloc.</p>
</item>
+ <tag><marker id="+rg"><c><![CDATA[+rg ReaderGroupsLimit]]></c></marker></tag>
+ <item>
+ <p>Limits the amount of reader groups used by read/write locks
+ optimized for read operations in the Erlang runtime system. By
+ default the reader groups limit equals 8.</p>
+ <p>When the amount of schedulers is less than or equal to the reader
+ groups limit, each scheduler has its own reader group. When the
+ amount of schedulers is larger than the reader groups limit,
+ schedulers share reader groups. Shared reader groups degrades
+ read lock and read unlock performance while a large amount of
+ reader groups degrades write lock performance, so the limit is a
+ tradeoff between performance for read operations and performance
+ for write operations. Each reader group currently consumes 64 byte
+ in each read/write lock. Also note that a runtime system using
+ shared reader groups benefits from <seealso marker="#+sbt">binding
+ schedulers to logical processors</seealso>, since the reader groups
+ are distributed better between schedulers.</p>
+ </item>
<tag><marker id="+S"><c><![CDATA[+S Schedulers:SchedulerOnline]]></c></marker></tag>
<item>
<p>Sets the amount of scheduler threads to create and scheduler
@@ -647,8 +708,8 @@
<seealso marker="erlang#system_flag_scheduler_bind_type">erlang:system_flag(scheduler_bind_type, default_bind)</seealso>.
</p></item>
</taglist>
- <p>Binding of schedulers are currently only supported on newer
- Linux and Solaris systems.</p>
+ <p>Binding of schedulers is currently only supported on newer
+ Linux, Solaris, FreeBSD, and Windows systems.</p>
<p>If no CPU topology is available when the <c>+sbt</c> flag
is processed and <c>BindType</c> is any other type than
<c>u</c>, the runtime system will fail to start. CPU
@@ -657,6 +718,22 @@
that the <c>+sct</c> flag may have to be passed before the
<c>+sbt</c> flag on the command line (in case no CPU topology
has been automatically detected).</p>
+ <p>The runtime system will by default bind schedulers to logical
+ processors using the <c>default_bind</c> bind type if the amount
+ of schedulers are at least equal to the amount of logical
+ processors configured, binding of schedulers is supported,
+ and a CPU topology is available at startup.
+ </p>
+ <p><em>NOTE:</em> If the Erlang runtime system is the only operating
+ system process that binds threads to logical processors, this
+ improves the performance of the runtime system. However, if other
+ operating system processes (as for example another Erlang runtime
+ system) also bind threads to logical processors, there might be a
+ performance penalty instead. If this is the case you, are advised
+ to unbind the schedulers using the <c>+sbtu</c> command line
+ argument, or by invoking
+ <seealso marker="erlang#system_flag_scheduler_bind_type">erlang:system_flag(scheduler_bind_type,
+ unbound)</seealso>.</p>
<p>For more information, see
<seealso marker="erlang#system_flag_scheduler_bind_type">erlang:system_flag(scheduler_bind_type, SchedulerBindType)</seealso>.
</p>
@@ -777,14 +854,28 @@
<p>For more information, see
<seealso marker="erlang#system_flag_cpu_topology">erlang:system_flag(cpu_topology, CpuTopology)</seealso>.</p>
</item>
+ <tag><marker id="+swt"><c>+swt very_low|low|medium|high|very_high</c></marker></tag>
+ <item>
+ <p>Set scheduler wakeup threshold. Default is <c>medium</c>.
+ The threshold determines when to wake up sleeping schedulers
+ when more work than can be handled by currently awake schedulers
+ exist. A low threshold will cause earlier wakeups, and a high
+ threshold will cause later wakeups. Early wakeups will
+ distribute work over multiple schedulers faster, but work will
+ more easily bounce between schedulers.
+ </p>
+ <p><em>NOTE:</em> This flag may be removed or changed at any time
+ without prior notice.
+ </p>
+ </item>
+ <tag><marker id="sched_thread_stack_size"><c><![CDATA[+sss size]]></c></marker></tag>
+ <item>
+ <p>Suggested stack size, in kilowords, for scheduler threads.
+ Valid range is 4-8192 kilowords. The default stack size
+ is OS dependent.</p>
+ </item>
</taglist>
</item>
- <tag><marker id="sched_thread_stack_size"><c><![CDATA[+sss size]]></c></marker></tag>
- <item>
- <p>Suggested stack size, in kilowords, for scheduler threads.
- Valid range is 4-8192 kilowords. The default stack size
- is OS dependent.</p>
- </item>
<tag><marker id="+t"><c><![CDATA[+t size]]></c></marker></tag>
<item>
<p>Set the maximum number of atoms the VM can handle. Default is 1048576.</p>
@@ -838,6 +929,25 @@
<seealso marker="kernel:error_logger#warning_map/0">error_logger(3)</seealso>
for further information.</p>
</item>
+ <tag><c><![CDATA[+zFlag Value]]></c></tag>
+ <item>
+ <p>Miscellaneous flags.</p>
+ <taglist>
+ <tag><marker id="+zdbbl"><c>+zdbbl size</c></marker></tag>
+ <item>
+ <p>Set the distribution buffer busy limit
+ (<seealso marker="erlang#system_info_dist_buf_busy_limit">dist_buf_busy_limit</seealso>)
+ in kilobytes. Valid range is 1-2097151. Default is 1024.</p>
+ <p>A larger buffer limit will allow processes to buffer
+ more outgoing messages over the distribution. When the
+ buffer limit has been reached, sending processes will be
+ suspended until the buffer size has shrunk. The buffer
+ limit is per distribution channel. A higher limit will
+ give lower latency and higher throughput at the expense
+ of higher memory usage.</p>
+ </item>
+ </taglist>
+ </item>
</taglist>
</section>
@@ -894,6 +1004,15 @@
add to the code path.
See <seealso marker="kernel:code">code(3)</seealso>.</p>
</item>
+ <tag><c><![CDATA[ERL_EPMD_ADDRESS]]></c></tag>
+ <item>
+ <p>This environment variable may be set to a comma-separated
+ list of IP addresses, in which case the
+ <seealso marker="epmd">epmd</seealso> daemon
+ will listen only on the specified address(es) and on the
+ loopback address (which is implicitly added to the list if it
+ has not been specified).</p>
+ </item>
<tag><c><![CDATA[ERL_EPMD_PORT]]></c></tag>
<item>
<p>This environment variable can contain the port number to use when
@@ -906,6 +1025,49 @@
</section>
<section>
+ <marker id="configuration"></marker>
+ <title>Configuration</title>
+ <p>The standard Erlang/OTP system can be re-configured to change the default
+ behavior on start-up.</p>
+ <taglist>
+ <tag>The .erlang Start-up File</tag>
+ <item>
+ <p>When Erlang/OTP is started, the system searches for a file named .erlang
+ in the directory where Erlang/OTP is started. If not found, the user's home
+ directory is searched for an .erlang file.</p>
+ <p>If an .erlang file is found, it is assumed to contain valid Erlang expressions.
+ These expressions are evaluated as if they were input to the shell.</p>
+ <p>A typical .erlang file contains a set of search paths, for example:</p>
+ <code type="none"><![CDATA[
+ io:format("executing user profile in HOME/.erlang\n",[]).
+ code:add_path("/home/calvin/test/ebin").
+ code:add_path("/home/hobbes/bigappl-1.2/ebin").
+ io:format(".erlang rc finished\n",[]).
+ ]]></code>
+ </item>
+ <tag>user_default and shell_default</tag>
+ <item>
+ <p>Functions in the shell which are not prefixed by a module name are assumed
+ to be functional objects (Funs), built-in functions (BIFs), or belong to the
+ module user_default or shell_default.</p>
+ <p>To include private shell commands, define them in a module user_default and
+ add the following argument as the first line in the .erlang file.</p>
+ <code type="none"><![CDATA[
+ code:load_abs("..../user_default").
+ ]]></code>
+ </item>
+ <tag>erl</tag>
+ <item>
+ <p>If the contents of .erlang are changed and a private version of
+ user_default is defined, it is possible to customize the Erlang/OTP environment.
+ More powerful changes can be made by supplying command line arguments in the
+ start-up script erl. Refer to erl(1) and <seealso marker="init">init(3)</seealso>
+ for further information.</p>
+ </item>
+ </taglist>
+ </section>
+
+ <section>
<title>SEE ALSO</title>
<p><seealso marker="init">init(3)</seealso>,
<seealso marker="erl_prim_loader">erl_prim_loader(3)</seealso>,
diff --git a/erts/doc/src/erl_dist_protocol.xml b/erts/doc/src/erl_dist_protocol.xml
index 5978af178a..6c725fc82d 100644
--- a/erts/doc/src/erl_dist_protocol.xml
+++ b/erts/doc/src/erl_dist_protocol.xml
@@ -5,7 +5,7 @@
<header>
<copyright>
<year>2007</year>
- <year>2007</year>
+ <year>2011</year>
<holder>Ericsson AB, All Rights Reserved</holder>
</copyright>
<legalnotice>
@@ -206,7 +206,7 @@ By default EPMD listens on port 4369.
<section>
<title>Unregister a node from the EPMD</title>
<p>
- A node unregister itself from the EPMD by simply closing the
+ A node unregisters itself from the EPMD by simply closing the
TCP connection towards EPMD established when the node was registered.
</p>
</section>
diff --git a/erts/doc/src/erl_driver.xml b/erts/doc/src/erl_driver.xml
index 5061230a33..2fb03954b6 100644
--- a/erts/doc/src/erl_driver.xml
+++ b/erts/doc/src/erl_driver.xml
@@ -4,7 +4,7 @@
<cref>
<header>
<copyright>
- <year>2001</year><year>2010</year>
+ <year>2001</year><year>2011</year>
<holder>Ericsson AB. All Rights Reserved.</holder>
</copyright>
<legalnotice>
@@ -56,16 +56,16 @@
instance is connected to an Erlang port. Every port has a port
owner process. Communication with the port is normally done
through the port owner process.</p>
- <p>Most of the functions takes the <c>port</c> handle as an
+ <p>Most of the functions take the <c>port</c> handle as an
argument. This identifies the driver instance. Note that this
port handle must be stored by the driver, it is not given when
the driver is called from the emulator (see
<seealso marker="driver_entry#emulator">driver_entry</seealso>).</p>
- <p>Some of the functions takes a parameter of type
+ <p>Some of the functions take a parameter of type
<c>ErlDrvBinary</c>, a driver binary. It should be both
- allocated and freed by the caller. Using a binary directly avoid
+ allocated and freed by the caller. Using a binary directly avoids
one extra copying of data.</p>
- <p>Many of the output functions has a "header buffer", with
+ <p>Many of the output functions have a "header buffer", with
<c>hbuf</c> and <c>hlen</c> parameters. This buffer is sent as a
list before the binary (or list, depending on port mode) that is
sent. This is convenient when matching on messages received from
@@ -92,7 +92,7 @@
with SMP support without being rewritten if driver
level locking is used.</p>
<note>
- <p>It is assumed that drivers does not access other drivers. If
+ <p>It is assumed that drivers do not access other drivers. If
drivers should access each other they have to provide their own
mechanism for thread safe synchronization. Such "inter driver
communication" is strongly discouraged.</p>
@@ -113,12 +113,12 @@
call-backs may be made from different threads.</p>
</note>
<p>Most functions in this API are <em>not</em> thread-safe, i.e.,
- they may <em>not</em> be called from an arbitrary thread. Function
+ they may <em>not</em> be called from an arbitrary thread. Functions
that are not documented as thread-safe may only be called from
driver call-backs or function calls descending from a driver
call-back call. Note that driver call-backs may be called from
different threads. This, however, is not a problem for any
- functions in this API, since the emulator have control over
+ function in this API, since the emulator has control over
these threads.</p>
<note>
<p>Functions not explicitly documented as thread-safe are
@@ -155,10 +155,10 @@
more information.</p>
</item>
<tag>Output functions</tag>
- <item>With the output functions, the driver sends data back
+ <item>With the output functions, the driver sends data back to
the emulator. They will be received as messages by the port owner
process, see <c>open_port/2</c>. The vector function and the
- function taking a driver binary is faster, because that avoid
+ function taking a driver binary are faster, because they avoid
copying the data buffer. There is also a fast way of sending
terms from the driver, without going through the binary term
format.</item>
@@ -193,14 +193,14 @@
use functionality from the POSIX thread API or the Windows
native thread API.
</p>
- <p>The Erlang driver thread API only return error codes when it is
+ <p>The Erlang driver thread API only returns error codes when it is
reasonable to recover from an error condition. If it isn't reasonable
to recover from an error condition, the whole runtime system is
terminated. For example, if a create mutex operation fails, an error
code is returned, but if a lock operation on a mutex fails, the
whole runtime system is terminated.
</p>
- <p>Note that there exist no "condition variable wait with timeout" in
+ <p>Note that there exists no "condition variable wait with timeout" in
the Erlang driver thread API. This is due to issues with
<c>pthread_cond_timedwait()</c>. When the system clock suddenly
is changed, it isn't always guaranteed that you will wake up from
@@ -241,7 +241,7 @@
to give you better error reports.
</p>
</item>
- <tag>Adding / remove drivers</tag>
+ <tag>Adding / removing drivers</tag>
<item>A driver can add and later remove drivers.</item>
<tag>Monitoring processes</tag>
<item>A driver can monitor a process that does not own a port.</item>
@@ -262,7 +262,7 @@
could, under rare circumstances, mean that drivers have to
be slightly modified. If so, this will of course be documented.
<c>ERL_DRV_EXTENDED_MINOR_VERSION</c> will be incremented when
- new features are added. The runtime system use the minor version
+ new features are added. The runtime system uses the minor version
of the driver to determine what features to use.
The runtime system will refuse to load a driver if the major
versions differ, or if the major versions are equal and the
@@ -273,7 +273,7 @@
It can, however, not make sure that it isn't incompatible. Therefore,
when loading a driver that doesn't use the extended driver
interface, there is a risk that it will be loaded also when
- the driver is incompatible. When the driver use the extended driver
+ the driver is incompatible. When the driver uses the extended driver
interface, the emulator can verify that it isn't of an incompatible
driver version. You are therefore advised to use the extended driver
interface.</p>
@@ -309,7 +309,7 @@ typedef struct ErlDrvSysInfo {
<seealso marker="#driver_system_info">driver_system_info()</seealso>
will write the system information when passed a reference to
a <c>ErlDrvSysInfo</c> structure. A description of the
- fields in the structure follow:
+ fields in the structure follows:
</p>
<taglist>
<tag><c>driver_major_version</c></tag>
@@ -347,14 +347,6 @@ typedef struct ErlDrvSysInfo {
<item>A value <c>!= 0</c> if the runtime system has SMP support;
otherwise, <c>0</c>.
</item>
- <tag><c>thread_support</c></tag>
- <item>A value <c>!= 0</c> if the runtime system has thread support;
- otherwise, <c>0</c>.
- </item>
- <tag><c>smp_support</c></tag>
- <item>A value <c>!= 0</c> if the runtime system has SMP support;
- otherwise, <c>0</c>.
- </item>
<tag><c>async_threads</c></tag>
<item>The number of async threads in the async thread pool used
by <seealso marker="#driver_async">driver_async()</seealso>
@@ -401,8 +393,8 @@ typedef struct ErlDrvBinary {
<seealso marker="#driver_binary_dec_refc">driver_binary_dec_refc()</seealso>.</p>
</note>
<p>Some driver calls, such as <c>driver_enq_binary</c>,
- increments the driver reference count, and others, such as
- <c>driver_deq</c> decrements it.</p>
+ increment the driver reference count, and others, such as
+ <c>driver_deq</c> decrement it.</p>
<p>Using a driver binary instead of a normal buffer, is often
faster, since the emulator doesn't need to copy the data,
only the pointer is used.</p>
@@ -415,7 +407,7 @@ typedef struct ErlDrvBinary {
<c>driver_outputv</c> calls, and in the queue. Also the
driver call-back <seealso marker="driver_entry#outputv">outputv</seealso> uses driver
binaries.</p>
- <p>If the driver of some reason or another, wants to keep a
+ <p>If the driver for some reason or another, wants to keep a
driver binary around, in a static variable for instance, the
reference count should be incremented,
and the binary can later be freed in the <seealso marker="driver_entry#stop">stop</seealso> call-back, with
@@ -423,7 +415,7 @@ typedef struct ErlDrvBinary {
<p>Note that since a driver binary is shared by the driver and
the emulator, a binary received from the emulator or sent to
the emulator, must not be changed by the driver.</p>
- <p>From erts version 5.5 (OTP release R11B), orig_bytes is
+ <p>Since erts version 5.5 (OTP release R11B), orig_bytes is
guaranteed to be properly aligned for storage of an array of
doubles (usually 8-byte aligned).</p>
</item>
@@ -447,7 +439,7 @@ typedef struct ErlIOVec {
int vsize;
int size;
SysIOVec* iov;
- >ErlDrvBinary** binv;
+ ErlDrvBinary** binv;
} ErlIOVec;
</code>
<p>The I/O vector used by the emulator and drivers, is a list
@@ -495,17 +487,17 @@ typedef struct ErlIOVec {
Currently, the only port specific data that the emulator
associates with the port data lock is the driver queue.</p>
<p>Normally a driver instance does not have a port data lock. If
- the driver instance want to use a port data lock, it has to
+ the driver instance wants to use a port data lock, it has to
create the port data lock by calling
<seealso marker="#driver_pdl_create">driver_pdl_create()</seealso>.
<em>NOTE</em>: Once the port data lock has been created, every
- access to data associated with the port data lock have to be done
+ access to data associated with the port data lock has to be done
while having the port data lock locked. The port data lock is
locked, and unlocked, respectively, by use of
<seealso marker="#driver_pdl_lock">driver_pdl_lock()</seealso>, and
<seealso marker="#driver_pdl_unlock">driver_pdl_unlock()</seealso>.</p>
<p>A port data lock is reference counted, and when the reference
- count reach zero, it will be destroyed. The emulator will at
+ count reaches zero, it will be destroyed. The emulator will at
least increment the reference count once when the lock is
created and decrement it once when the port associated with
the lock terminates. The emulator will also increment the
@@ -545,7 +537,7 @@ typedef struct ErlIOVec {
</p>
<taglist>
<tag>suggested_stack_size</tag>
- <item>A suggestion, in kilo-words, on how large stack to use. A value less
+ <item>A suggestion, in kilo-words, on how large a stack to use. A value less
than zero means default size.
</item>
</taglist>
@@ -648,7 +640,7 @@ typedef struct ErlIOVec {
opened.</p>
<p>The data is queued in the port owner process' message
queue. Note that this does not yield to the emulator. (Since
- the driver and the emulator runs in the same thread.)</p>
+ the driver and the emulator run in the same thread.)</p>
<p>The parameter <c>buf</c> points to the data to send, and
<c>len</c> is the number of bytes.</p>
<p>The return value for all output functions is 0. (Unless the
@@ -749,7 +741,7 @@ typedef struct ErlIOVec {
function <seealso marker="driver_entry#emulator">timeout</seealso> is called.</p>
<p>Note that there is only one timer on each driver instance;
setting a new timer will replace an older one.</p>
- <p>Return value i 0 (-1 only when the <c>timeout</c> driver
+ <p>Return value is 0 (-1 only when the <c>timeout</c> driver
function is <c>NULL</c>).</p>
</desc>
</func>
@@ -781,7 +773,7 @@ typedef struct ErlIOVec {
<marker id="driver_get_now"></marker>
<p>This function reads a timestamp into the memory pointed to by
the parameter <c>now</c>. See the description of <seealso marker="#ErlDrvNowData">ErlDrvNowData</seealso> for
- specification of it's fields. </p>
+ specification of its fields. </p>
<p>The return value is 0 unless the <c>now</c> pointer is not
valid, in which case it is &lt; 0. </p>
</desc>
@@ -799,20 +791,20 @@ typedef struct ErlIOVec {
event object must be a socket or pipe (or other object that
<c>select</c>/<c>poll</c> can use).
On windows, the Win32 API function <c>WaitForMultipleObjects</c>
- is used. This places other restriction on the event object.
+ is used. This places other restrictions on the event object.
Refer to the Win32 SDK documentation.</p>
<p>The <c>on</c> parameter should be <c>1</c> for setting events
and <c>0</c> for clearing them.</p>
- <p>The <c>mode</c> argument is bitwise-or combination of
+ <p>The <c>mode</c> argument is a bitwise-or combination of
<c>ERL_DRV_READ</c>, <c>ERL_DRV_WRITE</c> and <c>ERL_DRV_USE</c>.
- The first two specifies whether to wait for read events and/or write
+ The first two specify whether to wait for read events and/or write
events. A fired read event will call
<seealso marker="driver_entry#ready_input">ready_input</seealso>
while a fired write event will call
<seealso marker="driver_entry#ready_output">ready_output</seealso>.
</p>
<note>
- <p>Some OS (Windows) does not differ between read and write events.
+ <p>Some OS (Windows) do not differentiate between read and write events.
The call-back for a fired event then only depends on the value of <c>mode</c>.</p>
</note>
<p><c>ERL_DRV_USE</c> specifies if we are using the event object or if we want to close it.
@@ -834,9 +826,9 @@ typedef struct ErlIOVec {
as before. But it is recommended to update them to use <c>ERL_DRV_USE</c> and
<c>stop_select</c> to make sure that event objects are closed in a safe way.</p>
</note>
- <p>The return value is 0 (Failure, -1, only if the
+ <p>The return value is 0 (failure, -1, only if the
<c>ready_input</c>/<c>ready_output</c> is
- <c>NULL</c>.</p>
+ <c>NULL</c>).</p>
</desc>
</func>
<func>
@@ -1076,7 +1068,7 @@ typedef struct ErlIOVec {
array of <c>SysIOVec</c>s. It also returns the number of
elements in <c>vlen</c>. This is the only way to get data
out of the queue.</p>
- <p>Nothing is remove from the queue by this function, that must be done
+ <p>Nothing is removed from the queue by this function, that must be done
with <c>driver_deq</c>.</p>
<p>The returned array is suitable to use with the Unix system
call <c>writev</c>.</p>
@@ -1209,7 +1201,7 @@ typedef struct ErlIOVec {
<fsummary>Stop monitoring a process from a driver</fsummary>
<desc>
<marker id="driver_demonitor_process"></marker>
- <p>This function cancels an monitor created earlier. </p>
+ <p>This function cancels a monitor created earlier. </p>
<p>The function returns 0 if a monitor was removed and &gt; 0
if the monitor did no longer exist.</p>
</desc>
@@ -1326,7 +1318,7 @@ typedef struct ErlIOVec {
<p>This function signals to erlang that the driver has
encountered an EOF and should be closed, unless the port was
opened with the <c>eof</c> option, in that case eof is sent
- to the port. Otherwise, the port is close and an
+ to the port. Otherwise, the port is closed and an
<c>'EXIT'</c> message is sent to the port owner process.</p>
<p>The return value is 0.</p>
</desc>
@@ -1349,8 +1341,8 @@ typedef struct ErlIOVec {
(<c>driver_failure</c>).</p>
<p>The driver should fail only when in severe error situations,
when the driver cannot possibly keep open, for instance
- buffer allocation gets out of memory. Normal errors is more
- appropriate to handle with sending error codes with
+ buffer allocation gets out of memory. For normal errors
+ it is more appropriate to send error codes with
<c>driver_output</c>.</p>
<p>The return value is 0.</p>
</desc>
@@ -1371,7 +1363,7 @@ typedef struct ErlIOVec {
<p>This function returns the process id of the process that
made the current call to the driver. The process id can be
used with <c>driver_send_term</c> to send back data to the
- caller. <c>driver_caller()</c> only return valid data
+ caller. <c>driver_caller()</c> only returns valid data
when currently executing in one of the following driver
callbacks:</p>
<taglist>
@@ -1409,7 +1401,7 @@ typedef struct ErlIOVec {
tuple, the elements are given first, and then the tuple
term, with a count. Likewise for lists.</p>
<p>A tuple must be specified with the number of elements. (The
- elements precedes the <c>ERL_DRV_TUPLE</c> term.)</p>
+ elements precede the <c>ERL_DRV_TUPLE</c> term.)</p>
<p>A list must be specified with the number of elements,
including the tail, which is the last term preceding
<c>ERL_DRV_LIST</c>.</p>
@@ -1518,7 +1510,7 @@ ERL_DRV_EXT2TERM char *buf, ErlDrvUInt len
};
driver_output_term(port, spec, sizeof(spec) / sizeof(spec[0]));
]]></code>
- <p>If you want to pass a binary and doesn't already have the content
+ <p>If you want to pass a binary and don't already have the content
of the binary in an <c>ErlDrvBinary</c>, you can benefit from using
<c>ERL_DRV_BUF2BINARY</c> instead of creating an <c>ErlDrvBinary</c>
via <c>driver_alloc_binary()</c> and then pass the binary via
@@ -1565,7 +1557,7 @@ ERL_DRV_EXT2TERM char *buf, ErlDrvUInt len
<em>other</em> processes than the port owner process. The
<c>receiver</c> parameter specifies the process to receive
the data.</p>
- <p>The parameters <c>term</c> and <c>n</c> does the same thing
+ <p>The parameters <c>term</c> and <c>n</c> do the same thing
as in <seealso marker="#driver_output_term">driver_output_term</seealso>.</p>
<p>This function is only thread-safe when the emulator with SMP
support is used.</p>
@@ -1660,7 +1652,7 @@ ERL_DRV_EXT2TERM char *buf, ErlDrvUInt len
<desc>
<marker id="driver_lock_driver"></marker>
<p>This function locks the driver used by the port <c>port</c>
- in memory for the rest of the emulator process
+ in memory for the rest of the emulator process'
lifetime. After this call, the driver behaves as one of Erlang's
statically linked in drivers.</p>
</desc>
@@ -1904,7 +1896,7 @@ ERL_DRV_EXT2TERM char *buf, ErlDrvUInt len
corresponding to one of the involved thread identifiers
has terminated since the thread identifier was saved,
the result of <c>erl_drv_equal_tids()</c> might not give
- expected result.
+ the expected result.
</p></note>
<p>This function is thread-safe.</p>
</desc>
diff --git a/erts/doc/src/erl_ext_dist.xml b/erts/doc/src/erl_ext_dist.xml
index c2d58d1ef1..fd2da2cfe3 100644
--- a/erts/doc/src/erl_ext_dist.xml
+++ b/erts/doc/src/erl_ext_dist.xml
@@ -5,7 +5,7 @@
<header>
<copyright>
<year>2007</year>
- <year>2007</year>
+ <year>2011</year>
<holder>Ericsson AB, All Rights Reserved</holder>
</copyright>
<legalnotice>
diff --git a/erts/doc/src/erl_nif.xml b/erts/doc/src/erl_nif.xml
index 0dd46a951a..48839e9081 100644
--- a/erts/doc/src/erl_nif.xml
+++ b/erts/doc/src/erl_nif.xml
@@ -4,7 +4,7 @@
<cref>
<header>
<copyright>
- <year>2001</year><year>2009</year>
+ <year>2001</year><year>2011</year>
<holder>Ericsson AB. All Rights Reserved.</holder>
</copyright>
<legalnotice>
@@ -34,18 +34,29 @@
<lib>erl_nif</lib>
<libsummary>API functions for an Erlang NIF library</libsummary>
<description>
- <warning><p>The NIF concept was introduced in R13B03 as an
- EXPERIMENTAL feature. The interfaces may be changed in any way
- in coming releases. The plan is however to lift the experimental label and
- maintain interface backward compatibility from R14B.</p>
- <p>Incompatible changes in <em>R13B04</em>:</p>
+ <note><p>The NIF concept is officially supported from R14B. NIF source code
+ written for earlier experimental versions might need adaption to run on R14B.</p>
+ <p>No incompatible changes between <em>R14B</em> and R14A.</p>
+ <p>Incompatible changes between <em>R14A</em> and R13B04:</p>
+ <list>
+ <item>Environment argument removed for <c>enif_alloc</c>,
+ <c>enif_realloc</c>, <c>enif_free</c>, <c>enif_alloc_binary</c>,
+ <c>enif_realloc_binary</c>, <c>enif_release_binary</c>,
+ <c>enif_alloc_resource</c>, <c>enif_release_resource</c>,
+ <c>enif_is_identical</c> and <c>enif_compare</c>.</item>
+ <item>Character encoding argument added to <c>enif_get_atom</c>
+ and <c>enif_make_existing_atom</c>.</item>
+ <item>Module argument added to <c>enif_open_resource_type</c>
+ while changing name spaces of resource types from global to module local.</item>
+ </list>
+ <p>Incompatible changes between <em>R13B04</em> and R13B03:</p>
<list>
<item>The function prototypes of the NIFs have changed to expect <c>argc</c> and <c>argv</c>
arguments. The arity of a NIF is by that no longer limited to 3.</item>
<item><c>enif_get_data</c> renamed as <c>enif_priv_data</c>.</item>
<item><c>enif_make_string</c> got a third argument for character encoding.</item>
</list>
- </warning>
+ </note>
<p>A NIF library contains native implementation of some functions
of an Erlang module. The native implemented functions (NIFs) are
@@ -109,9 +120,9 @@ ok
the new directive <seealso
marker="doc/reference_manual:code_loading#on_load">on_load</seealso> to automatically
load the NIF library when the module is loaded.</p>
- <note><p>A NIF must be exported or used locally by the module (or both).
- An unused local stub function will be optimized away by the compiler
- causing loading of the NIF library to fail.</p>
+ <note><p>A NIF does not have to be exported, it can be local to the module.
+ Note however that unused local stub functions will be optimized
+ away by the compiler causing loading of the NIF library to fail.</p>
</note>
<p>A loaded NIF library is tied to the Erlang module code version
that loaded it. If the module is upgraded with a new version, the
@@ -122,7 +133,7 @@ ok
will be shared as well. To avoid unintentionally shared static
data, each Erlang module code can keep its own private data. This
private data can be set when the NIF library is loaded and
- then retrieved by calling <seealso marker="#enif_priv_data">enif_priv_data()</seealso>.</p>
+ then retrieved by calling <seealso marker="#enif_priv_data">enif_priv_data</seealso>.</p>
<p>There is no way to explicitly unload a NIF library. A library will be
automatically unloaded when the module code that it belongs to is purged
by the code server. A NIF library will also be unloaded if it is replaced
@@ -137,14 +148,20 @@ ok
<taglist>
<tag>Read and write Erlang terms</tag>
<item><p>Any Erlang terms can be passed to a NIF as function arguments and
- be returned as function return values. The terms are of C-type <c>ERL_NIF_TERM</c>
+ be returned as function return values. The terms are of C-type
+ <seealso marker="#ERL_NIF_TERM">ERL_NIF_TERM</seealso>
and can only be read or written using API functions. Most functions to read
the content of a term are prefixed <c>enif_get_</c> and usually return
true (or false) if the term was of the expected type (or not).
The functions to write terms are all prefixed <c>enif_make_</c> and usually
return the created <c>ERL_NIF_TERM</c>. There are also some functions
to query terms, like <c>enif_is_atom</c>, <c>enif_is_identical</c> and
- <c>enif_compare</c>.</p></item>
+ <c>enif_compare</c>.</p>
+ <p>All terms of type <c>ERL_NIF_TERM</c> belong to an environment of type
+ <seealso marker="#ErlNifEnv">ErlNifEnv</seealso>. The lifetime of a term is
+ controlled by the lifetime of its environment object. All API functions that read
+ or write terms has the environment, that the term belongs to, as the first
+ function argument.</p></item>
<tag>Binaries</tag>
<item><p>Terms of type binary are accessed with the help of the struct type
<seealso marker="#ErlNifBinary">ErlNifBinary</seealso>
@@ -161,8 +178,10 @@ ok
<seealso marker="#enif_release_binary">enif_release_binary</seealso>
or made read-only by transferring it to an Erlang term with
<seealso marker="#enif_make_binary">enif_make_binary</seealso>.
- But it does not have do happen in the same NIF call. Read-only binaries
- does not have to be released.</p>
+ But it does not have to happen in the same NIF call. Read-only binaries
+ do not have to be released.</p>
+ <p><seealso marker="#enif_make_new_binary">enif_make_new_binary</seealso>
+ can be used as a shortcut to allocate and return a binary in the same NIF call.</p>
<p>Binaries are sequences of whole bytes. Bitstrings with an arbitrary
bit length have no support yet.</p>
</item>
@@ -170,67 +189,83 @@ ok
<item><p>The use of resource objects is a way to return pointers to
native data structures from a NIF in a safe way. A resource object is
just a block of memory allocated with
- <seealso marker="#enif_alloc_resource">enif_alloc_resource()</seealso>.
+ <seealso marker="#enif_alloc_resource">enif_alloc_resource</seealso>.
A handle ("safe pointer") to this memory block can then be returned to Erlang by the use of
- <seealso marker="#enif_make_resource">enif_make_resource()</seealso>.
+ <seealso marker="#enif_make_resource">enif_make_resource</seealso>.
The term returned by <c>enif_make_resource</c>
- is totally opaque in nature. It can be stored and passed between processses
- on the same node, but the only real end usage is to pass it back as argument to a NIF.
- The NIF can then do <seealso marker="#enif_get_resource">enif_get_resource()</seealso>
+ is totally opaque in nature. It can be stored and passed between processes
+ on the same node, but the only real end usage is to pass it back as an argument to a NIF.
+ The NIF can then call <seealso marker="#enif_get_resource">enif_get_resource</seealso>
and get back a pointer to the memory block that is guaranteed to still be
valid. A resource object will not be deallocated until the last handle term
has been garbage collected by the VM and the resource has been
- released with <seealso marker="#enif_release_resource">enif_release_resource()</seealso>
+ released with <seealso marker="#enif_release_resource">enif_release_resource</seealso>
(not necessarily in that order).</p>
<p>All resource objects are created as instances of some <em>resource type</em>.
This makes resources from different modules to be distinguishable.
A resource type is created by calling
- <seealso marker="#enif_open_resource_type">enif_open_resource_type()</seealso>
+ <seealso marker="#enif_open_resource_type">enif_open_resource_type</seealso>
when a library is loaded. Objects of that resource type can then later be allocated
and <c>enif_get_resource</c> verifies that the resource is of the expected type.
A resource type can have a user supplied destructor function that is
automatically called when resources of that type are released (by either
the garbage collector or <c>enif_release_resource</c>). Resource types
- are uniquely identified by a supplied name string.</p>
- <p>Resource types support upgrade in runtime by allowing a loaded NIF
- library to takeover an already existing resource type and thereby
- "inherit" all existing objects of that type. The destructor of the new
- library will thereafter be called for the inherited objects and the
- library with the old destructor function can be safely unloaded. Existing
- resource objects, of a module that is upgraded, must either be deleted
- or taken over by the new NIF library. The unloading of a library will be
- postponed as long as it exists resource objects with a destructor
- function in the library.
- </p>
- <p>Here is a template example of how to create and return a resource object.</p>
+ are uniquely identified by a supplied name string and the name of the
+ implementing module.</p>
+ <marker id="enif_resource_example"/><p>Here is a template example of how to create and return a resource object.</p>
<p/>
<code type="none">
ERL_NIF_TERM term;
- MyStruct* ptr = enif_alloc_resource(env, my_resource_type, sizeof(MyStruct));
+ MyStruct* obj = enif_alloc_resource(my_resource_type, sizeof(MyStruct));
/* initialize struct ... */
- term = enif_make_resource(env, ptr);
+ term = enif_make_resource(env, obj);
if (keep_a_reference_of_our_own) {
- /* store 'ptr' in static variable, private data or other resource object */
+ /* store 'obj' in static variable, private data or other resource object */
}
else {
- enif_release_resource(env, obj);
+ enif_release_resource(obj);
/* resource now only owned by "Erlang" */
}
return term;
-}
-</code>
-
+ </code>
+ <p>Note that once <c>enif_make_resource</c> creates the term to
+ return to Erlang, the code can choose to either keep its own
+ native pointer to the allocated struct and release it later, or
+ release it immediately and rely solely on the garbage collector
+ to eventually deallocate the resource object when it collects
+ the term.</p>
+ <p>Another usage of resource objects is to create binary terms with
+ user defined memory management.
+ <seealso marker="#enif_make_resource_binary">enif_make_resource_binary</seealso>
+ will create a binary term that is connected to a resource object. The
+ destructor of the resource will be called when the binary is garbage
+ collected, at which time the binary data can be released. An example of
+ this can be a binary term consisting of data from a <c>mmap</c>'ed file.
+ The destructor can then do <c>munmap</c> to release the memory
+ region.</p>
+ <p>Resource types support upgrade in runtime by allowing a loaded NIF
+ library to takeover an already existing resource type and thereby
+ "inherit" all existing objects of that type. The destructor of the new
+ library will thereafter be called for the inherited objects and the
+ library with the old destructor function can be safely unloaded. Existing
+ resource objects, of a module that is upgraded, must either be deleted
+ or taken over by the new NIF library. The unloading of a library will be
+ postponed as long as there exist resource objects with a destructor
+ function in the library.
+ </p>
</item>
<tag>Threads and concurrency</tag>
<item><p>A NIF is thread-safe without any explicit synchronization as
long as it acts as a pure function and only reads the supplied
arguments. As soon as you write towards a shared state either through
static variables or <seealso marker="#enif_priv_data">enif_priv_data</seealso>
- you need to supply your own explicit synchronization. Resource objects
- will also require synchronization if you treat them as mutable.</p>
+ you need to supply your own explicit synchronization. This includes terms
+ in process independent environments that are shared between threads.
+ Resource objects will also require synchronization if you treat them as
+ mutable.</p>
<p>The library initialization callbacks <c>load</c>, <c>reload</c> and
<c>upgrade</c> are all thread-safe even for shared state data.</p>
<p>Avoid doing lengthy work in NIF calls as that may degrade the
@@ -262,8 +297,8 @@ ok
<item><p><c>load</c> is called when the NIF library is loaded
and there is no previously loaded library for this module.</p>
<p><c>*priv_data</c> can be set to point to some private data
- that the library needs in able to keep a state between NIF
- calls. <c>enif_priv_data()</c> will return this pointer.
+ that the library needs in order to keep a state between NIF
+ calls. <c>enif_priv_data</c> will return this pointer.
<c>*priv_data</c> will be initialized to NULL when <c>load</c> is
called.</p>
<p><c>load_info</c> is the second argument to <seealso
@@ -315,19 +350,37 @@ ok
<item>
<p>Variables of type <c>ERL_NIF_TERM</c> can refer to any Erlang term.
This is an opaque type and values of it can only by used either as
- arguments to API functions or as return values from NIFs. A variable of
- type <c>ERL_NIF_TERM</c> is only valid until the NIF call, where it was
- obtained, returns.</p>
+ arguments to API functions or as return values from NIFs. All
+ <c>ERL_NIF_TERM</c>'s belong to an environment
+ (<seealso marker="#ErlNifEnv">ErlNifEnv</seealso>). A term can not be
+ destructed individually, it is valid until its environment is destructed.</p>
</item>
<tag><marker id="ErlNifEnv"/>ErlNifEnv</tag>
<item>
- <p><c>ErlNifEnv</c> contains information about the context in
- which a NIF call is made. This pointer should not be
- dereferenced in any way, but only passed on to API
- functions. An <c>ErlNifEnv</c> pointer is only valid until
- the function, where is what supplied as argument,
- returns. There is thus useless and dangerous to store <c>ErlNifEnv</c>
- pointers in between NIF calls.</p>
+ <p><c>ErlNifEnv</c> represents an environment that can host Erlang terms.
+ All terms in an environment are valid as long as the environment is valid.
+ <c>ErlNifEnv</c> is an opaque type and pointers to it can only be passed
+ on to API functions. There are two types of environments; process
+ bound and process independent.</p>
+ <p>A <em>process bound environment</em> is passed as the first argument to all NIFs.
+ All function arguments passed to a NIF will belong to that environment.
+ The return value from a NIF must also be a term belonging to the same
+ environment.
+ In addition a process bound environment contains transient information
+ about the calling Erlang process. The environment is only valid in the
+ thread where it was supplied as argument until the NIF returns. It is
+ thus useless and dangerous to store pointers to process bound
+ environments between NIF calls. </p>
+ <p>A <em>process independent environment</em> is created by calling
+ <seealso marker="#enif_alloc_env">enif_alloc_env</seealso>. It can be
+ used to store terms between NIF calls and to send terms with
+ <seealso marker="#enif_send">enif_send</seealso>. A process
+ independent environment with all its terms is valid until you explicitly
+ invalidates it with <seealso marker="#enif_free_env">enif_free_env</seealso>
+ or <c>enif_send</c>.</p>
+ <p>All elements of a list/tuple must belong to the same environment as the
+ list/tuple itself. Terms can be copied between environments with
+ <seealso marker="#enif_make_copy">enif_make_copy</seealso>.</p>
</item>
<tag><marker id="ErlNifFunc"/>ErlNifFunc</tag>
<item>
@@ -361,7 +414,18 @@ typedef struct {
<p><c>ErlNifBinary</c> contains transient information about an
inspected binary term. <c>data</c> is a pointer to a buffer
of <c>size</c> bytes with the raw content of the binary.</p>
+ <p>Note that <c>ErlNifBinary</c> is a semi-opaque type and you are
+ only allowed to read fields <c>size</c> and <c>data</c>.</p>
</item>
+ <tag><marker id="ErlNifPid"/>ErlNifPid</tag>
+ <item>
+ <p><c>ErlNifPid</c> is a process identifier (pid). In contrast to
+ pid terms (instances of <c>ERL_NIF_TERM</c>), <c>ErlNifPid</c>'s are self
+ contained and not bound to any
+ <seealso marker="#ErlNifEnv">environment</seealso>. <c>ErlNifPid</c>
+ is an opaque type.</p>
+ </item>
+
<tag><marker id="ErlNifResourceType"/>ErlNifResourceType</tag>
<item>
<p>Each instance of <c>ErlNifResourceType</c> represent a class of
@@ -386,9 +450,9 @@ typedef enum {
ERL_NIF_LATIN1
}ErlNifCharEncoding;
</code>
- <p>The character encoding used in strings. The only supported
- encoding is currently <c>ERL_NIF_LATIN1</c> for iso-latin-1
- (8-bit ascii).</p>
+ <p>The character encoding used in strings and atoms. The only
+ supported encoding is currently <c>ERL_NIF_LATIN1</c> for
+ iso-latin-1 (8-bit ascii).</p>
</item>
<tag><marker id="ErlNifSysInfo"/>ErlNifSysInfo</tag>
<item>
@@ -396,33 +460,53 @@ typedef enum {
to return information about the runtime system. Contains currently
the exact same content as <seealso marker="erl_driver#ErlDrvSysInfo">ErlDrvSysInfo</seealso>.</p>
</item>
+ <tag><marker id="ErlNifSInt64"/>ErlNifSInt64</tag>
+ <item><p>A native signed 64-bit integer type.</p></item>
+ <tag><marker id="ErlNifUInt64"/>ErlNifUInt64</tag>
+ <item><p>A native unsigned 64-bit integer type.</p></item>
</taglist>
</section>
<funcs>
- <func><name><ret>void*</ret><nametext>enif_alloc(ErlNifEnv* env, size_t size)</nametext></name>
+ <func><name><ret>void*</ret><nametext>enif_alloc(size_t size)</nametext></name>
<fsummary>Allocate dynamic memory.</fsummary>
<desc><p>Allocate memory of <c>size</c> bytes. Return NULL if allocation failed.</p></desc>
</func>
- <func><name><ret>int</ret><nametext>enif_alloc_binary(ErlNifEnv* env, unsigned size, ErlNifBinary* bin)</nametext></name>
+ <func><name><ret>int</ret><nametext>enif_alloc_binary(size_t size, ErlNifBinary* bin)</nametext></name>
<fsummary>Create a new binary.</fsummary>
- <desc><p>Allocate a new binary of size of <c>size</c>
+ <desc><p>Allocate a new binary of size <c>size</c>
bytes. Initialize the structure pointed to by <c>bin</c> to
refer to the allocated binary. The binary must either be released by
- <seealso marker="#enif_release_binary">enif_release_binary()</seealso>
+ <seealso marker="#enif_release_binary">enif_release_binary</seealso>
or ownership transferred to an Erlang term with
- <seealso marker="#enif_make_binary">enif_make_binary()</seealso>.
+ <seealso marker="#enif_make_binary">enif_make_binary</seealso>.
An allocated (and owned) <c>ErlNifBinary</c> can be kept between NIF
calls.</p>
- <p>Return false if allocation failed.</p>
+ <p>Return true on success or false if allocation failed.</p>
+ </desc>
+ </func>
+ <func><name><ret>ErlNifEnv*</ret><nametext>enif_alloc_env()</nametext></name>
+ <fsummary>Create a new environment</fsummary>
+ <desc><p>Allocate a new process independent environment. The environment can
+ be used to hold terms that is not bound to any process. Such terms can
+ later be copied to a process environment with
+ <seealso marker="#enif_make_copy">enif_make_copy</seealso>
+ or be sent to a process as a message with <seealso marker="#enif_send">enif_send</seealso>.</p>
+ <p>Return pointer to the new environment.</p>
</desc>
</func>
- <func><name><ret>void*</ret><nametext>enif_alloc_resource(ErlNifEnv* env, ErlNifResourceType* type, unsigned size)</nametext></name>
+ <func><name><ret>void*</ret><nametext>enif_alloc_resource(ErlNifResourceType* type, unsigned size)</nametext></name>
<fsummary>Allocate a memory managed resource object</fsummary>
<desc><p>Allocate a memory managed resource object of type <c>type</c> and size <c>size</c> bytes.</p></desc>
</func>
- <func><name><ret>int</ret><nametext>enif_compare(ErlNifEnv* env, ERL_NIF_TERM lhs, ERL_NIF_TERM rhs)</nametext></name>
+ <func><name><ret>void</ret><nametext>enif_clear_env(ErlNifEnv* env)</nametext></name>
+ <fsummary>Clear an environment for reuse.</fsummary>
+ <desc><p>Free all terms in an environment and clear it for reuse. The environment must
+ have been allocated with <seealso marker="#enif_alloc_env">enif_alloc_env</seealso>.
+ </p></desc>
+ </func>
+ <func><name><ret>int</ret><nametext>enif_compare(ERL_NIF_TERM lhs, ERL_NIF_TERM rhs)</nametext></name>
<fsummary>Compare two terms</fsummary>
<desc><p>Return an integer less than, equal to, or greater than
zero if <c>lhs</c> is found, respectively, to be less than,
@@ -432,77 +516,104 @@ typedef enum {
</func>
<func><name><ret>void</ret><nametext>enif_cond_broadcast(ErlNifCond *cnd)</nametext></name>
<fsummary></fsummary>
- <desc><p>Same as <seealso marker="erl_driver#erl_drv_cond_broadcast">erl_drv_cond_broadcast()</seealso>.
+ <desc><p>Same as <seealso marker="erl_driver#erl_drv_cond_broadcast">erl_drv_cond_broadcast</seealso>.
</p></desc>
</func>
<func><name><ret>ErlNifCond*</ret><nametext>enif_cond_create(char *name)</nametext></name>
<fsummary></fsummary>
- <desc><p>Same as <seealso marker="erl_driver#erl_drv_cond_create">erl_drv_cond_create()</seealso>.
+ <desc><p>Same as <seealso marker="erl_driver#erl_drv_cond_create">erl_drv_cond_create</seealso>.
</p></desc>
</func>
<func><name><ret>void</ret><nametext>enif_cond_destroy(ErlNifCond *cnd)</nametext></name>
<fsummary></fsummary>
- <desc><p>Same as <seealso marker="erl_driver#erl_drv_cond_destroy">erl_drv_cond_destroy()</seealso>.
+ <desc><p>Same as <seealso marker="erl_driver#erl_drv_cond_destroy">erl_drv_cond_destroy</seealso>.
</p></desc>
</func>
<func><name><ret>void</ret><nametext>enif_cond_signal(ErlNifCond *cnd)</nametext></name>
<fsummary></fsummary>
- <desc><p>Same as <seealso marker="erl_driver#erl_drv_cond_signal">erl_drv_cond_signal()</seealso>.
+ <desc><p>Same as <seealso marker="erl_driver#erl_drv_cond_signal">erl_drv_cond_signal</seealso>.
</p></desc>
</func>
<func><name><ret>void</ret><nametext>enif_cond_wait(ErlNifCond *cnd, ErlNifMutex *mtx)</nametext></name>
<fsummary></fsummary>
- <desc><p>Same as <seealso marker="erl_driver#erl_drv_cond_wait">erl_drv_cond_wait()</seealso>.
+ <desc><p>Same as <seealso marker="erl_driver#erl_drv_cond_wait">erl_drv_cond_wait</seealso>.
</p></desc>
</func>
<func><name><ret>int</ret><nametext>enif_equal_tids(ErlNifTid tid1, ErlNifTid tid2)</nametext></name>
<fsummary></fsummary>
- <desc><p>Same as <seealso marker="erl_driver#erl_drv_equal_tids">erl_drv_equal_tids()</seealso>.
+ <desc><p>Same as <seealso marker="erl_driver#erl_drv_equal_tids">erl_drv_equal_tids</seealso>.
</p></desc>
</func>
- <func><name><ret>void</ret><nametext>enif_free(ErlNifEnv* env, void* ptr)</nametext></name>
+ <func><name><ret>void</ret><nametext>enif_free(void* ptr)</nametext></name>
<fsummary>Free dynamic memory</fsummary>
<desc><p>Free memory allocated by <c>enif_alloc</c>.</p></desc>
</func>
- <func><name><ret>int</ret><nametext>enif_get_atom(ErlNifEnv* env,
- ERL_NIF_TERM term, char* buf, unsigned size)
- </nametext></name>
+ <func><name><ret>void</ret><nametext>enif_free_env(ErlNifEnv* env)</nametext></name>
+ <fsummary>Free an environment allocated with enif_alloc_env</fsummary>
+ <desc><p>Free an environment allocated with <seealso marker="#enif_alloc_env">enif_alloc_env</seealso>.
+ All terms created in the environment will be freed as well.</p></desc>
+ </func>
+ <func><name><ret>int</ret><nametext>enif_get_atom(ErlNifEnv* env, ERL_NIF_TERM term, char* buf, unsigned size, ErlNifCharEncoding encode)</nametext></name>
<fsummary>Get the text representation of an atom term</fsummary>
<desc><p>Write a null-terminated string, in the buffer pointed to by
<c>buf</c> of size <c>size</c>, consisting of the string
- representation of the atom <c>term</c>. Return the number of bytes
- written (including terminating null character) or 0 if
+ representation of the atom <c>term</c> with encoding
+ <seealso marker="#ErlNifCharEncoding">encode</seealso>. Return
+ the number of bytes written (including terminating null character) or 0 if
<c>term</c> is not an atom with maximum length of
<c>size-1</c>.</p></desc>
</func>
+ <func><name><ret>int</ret><nametext>enif_get_atom_length(ErlNifEnv* env, ERL_NIF_TERM term, unsigned* len, ErlNifCharEncoding encode)</nametext></name>
+ <fsummary>Get the length of atom <c>term</c>.</fsummary>
+ <desc><p>Set <c>*len</c> to the length (number of bytes excluding
+ terminating null character) of the atom <c>term</c> with encoding
+ <c>encode</c>. Return true on success or false if <c>term</c> is not an
+ atom.</p></desc>
+ </func>
<func><name><ret>int</ret><nametext>enif_get_double(ErlNifEnv* env, ERL_NIF_TERM term, double* dp)</nametext></name>
<fsummary>Read a floating-point number term.</fsummary>
<desc><p>Set <c>*dp</c> to the floating point value of
- <c>term</c> or return false if <c>term</c> is not a float.</p></desc>
+ <c>term</c>. Return true on success or false if <c>term</c> is not a float.</p></desc>
</func>
<func><name><ret>int</ret><nametext>enif_get_int(ErlNifEnv* env, ERL_NIF_TERM term, int* ip)</nametext></name>
- <fsummary>Read an integer term.</fsummary>
+ <fsummary>Read an integer term</fsummary>
+ <desc><p>Set <c>*ip</c> to the integer value of
+ <c>term</c>. Return true on success or false if <c>term</c> is not an
+ integer or is outside the bounds of type <c>int</c>.</p></desc>
+ </func>
+ <func><name><ret>int</ret><nametext>enif_get_int64(ErlNifEnv* env, ERL_NIF_TERM term, ErlNifSInt64* ip)</nametext></name>
+ <fsummary>Read a 64-bit integer term</fsummary>
<desc><p>Set <c>*ip</c> to the integer value of
- <c>term</c> or return false if <c>term</c> is not an integer or is
- outside the bounds of type <c>int</c></p></desc>
+ <c>term</c>. Return true on success or false if <c>term</c> is not an
+ integer or is outside the bounds of a signed 64-bit integer.</p></desc>
+ </func>
+ <func><name><ret>int</ret><nametext>enif_get_local_pid(ErlNifEnv* env, ERL_NIF_TERM term, ErlNifPid* pid)</nametext></name>
+ <fsummary>Read an local pid term</fsummary>
+ <desc><p>If <c>term</c> is the pid of a node local process, initialize the
+ pid variable <c>*pid</c> from it and return true. Otherwise return false.
+ No check if the process is alive is done.</p></desc>
</func>
<func><name><ret>int</ret><nametext>enif_get_list_cell(ErlNifEnv* env, ERL_NIF_TERM list, ERL_NIF_TERM* head, ERL_NIF_TERM* tail)</nametext></name>
<fsummary>Get head and tail from a list</fsummary>
<desc><p>Set <c>*head</c> and <c>*tail</c> from
- <c>list</c> or return false if <c>list</c> is not a non-empty
- list.</p></desc>
+ <c>list</c> and return true, or return false if <c>list</c> is not a
+ non-empty list.</p></desc>
+ </func>
+ <func><name><ret>int</ret><nametext>enif_get_list_length(ErlNifEnv* env, ERL_NIF_TERM term, unsigned* len)</nametext></name>
+ <fsummary>Get the length of list <c>term</c>.</fsummary>
+ <desc><p>Set <c>*len</c> to the length of list <c>term</c> and return true,
+ or return false if <c>term</c> is not a list.</p></desc>
</func>
<func><name><ret>int</ret><nametext>enif_get_long(ErlNifEnv* env, ERL_NIF_TERM term, long int* ip)</nametext></name>
<fsummary>Read an long integer term.</fsummary>
- <desc><p>Set <c>*ip</c> to the long integer value of
- <c>term</c> or return false if <c>term</c> is not an integer or is
+ <desc><p>Set <c>*ip</c> to the long integer value of <c>term</c> and
+ return true, or return false if <c>term</c> is not an integer or is
outside the bounds of type <c>long int</c>.</p></desc>
</func>
<func><name><ret>int</ret><nametext>enif_get_resource(ErlNifEnv* env, ERL_NIF_TERM term, ErlNifResourceType* type, void** objp)</nametext></name>
<fsummary>Get the pointer to a resource object</fsummary>
- <desc><p>Set <c>*objp</c> to point to the resource object referred to by <c>term</c>.
- The pointer is valid until the calling NIF returns and should not be released.</p>
- <p>Return false if <c>term</c> is not a handle to a resource object
+ <desc><p>Set <c>*objp</c> to point to the resource object referred to by <c>term</c>.</p>
+ <p>Return true on success or false if <c>term</c> is not a handle to a resource object
of type <c>type</c>.</p></desc>
</func>
<func><name><ret>int</ret><nametext>enif_get_string(ErlNifEnv* env,
@@ -527,27 +638,32 @@ typedef enum {
<c>*arity</c> to the number of elements. Note that the array
is read-only and <c>(*array)[N-1]</c> will be the Nth element of
the tuple. <c>*array</c> is undefined if the arity of the tuple
- is zero.</p><p>Return false if <c>term</c> is not a
+ is zero.</p><p>Return true on success or false if <c>term</c> is not a
tuple.</p></desc>
</func>
<func><name><ret>int</ret><nametext>enif_get_uint(ErlNifEnv* env, ERL_NIF_TERM term, unsigned int* ip)</nametext></name>
<fsummary>Read an unsigned integer term.</fsummary>
- <desc><p>Set <c>*ip</c> to the unsigned integer value of
- <c>term</c> or return false if <c>term</c> is not an unsigned integer or is
- outside the bounds of type <c>unsigned int</c></p></desc>
+ <desc><p>Set <c>*ip</c> to the unsigned integer value of <c>term</c> and
+ return true, or return false if <c>term</c> is not an unsigned integer or
+ is outside the bounds of type <c>unsigned int</c>.</p></desc>
+ </func>
+ <func><name><ret>int</ret><nametext>enif_get_uint64(ErlNifEnv* env, ERL_NIF_TERM term, ErlNifUInt64* ip)</nametext></name>
+ <fsummary>Read an unsigned 64-bit integer term.</fsummary>
+ <desc><p>Set <c>*ip</c> to the unsigned integer value of <c>term</c> and
+ return true, or return false if <c>term</c> is not an unsigned integer or
+ is outside the bounds of an unsigned 64-bit integer.</p></desc>
</func>
-
<func><name><ret>int</ret><nametext>enif_get_ulong(ErlNifEnv* env, ERL_NIF_TERM term, unsigned long* ip)</nametext></name>
<fsummary>Read an unsigned integer term.</fsummary>
- <desc><p>Set <c>*ip</c> to the unsigned long integer value of
- <c>term</c> or return false if <c>term</c> is not an unsigned integer or is
- outside the bounds of type <c>unsigned long</c></p></desc>
+ <desc><p>Set <c>*ip</c> to the unsigned long integer value of <c>term</c>
+ and return true, or return false if <c>term</c> is not an unsigned integer or is
+ outside the bounds of type <c>unsigned long</c>.</p></desc>
</func>
<func><name><ret>int</ret><nametext>enif_inspect_binary(ErlNifEnv* env, ERL_NIF_TERM bin_term, ErlNifBinary* bin)</nametext></name>
<fsummary>Inspect the content of a binary</fsummary>
<desc><p>Initialize the structure pointed to by <c>bin</c> with
information about the binary term
- <c>bin_term</c>. Return false if <c>bin_term</c> is not a binary.</p></desc>
+ <c>bin_term</c>. Return true on success or false if <c>bin_term</c> is not a binary.</p></desc>
</func>
<func><name><ret>int</ret><nametext>enif_inspect_iolist_as_binary(ErlNifEnv*
env, ERL_NIF_TERM term, ErlNifBinary* bin)
@@ -556,7 +672,7 @@ typedef enum {
<desc><p>Initialize the structure pointed to by <c>bin</c> with one
continuous buffer with the same byte content as <c>iolist</c>. As with
inspect_binary, the data pointed to by <c>bin</c> is transient and does
- not need to be released. Return false if <c>iolist</c> is not an
+ not need to be released. Return true on success or false if <c>iolist</c> is not an
iolist.</p>
</desc>
</func>
@@ -572,11 +688,15 @@ typedef enum {
<fsummary>Determine if a term is an empty list</fsummary>
<desc><p>Return true if <c>term</c> is an empty list.</p></desc>
</func>
+ <marker id="enif_is_exception"/><func><name><ret>int</ret><nametext>enif_is_exception(ErlNifEnv* env, ERL_NIF_TERM term)</nametext></name>
+ <fsummary>Determine if a term is an exception</fsummary>
+ <desc><p>Return true if <c>term</c> is an exception.</p></desc>
+ </func>
<func><name><ret>int</ret><nametext>enif_is_fun(ErlNifEnv* env, ERL_NIF_TERM term)</nametext></name>
<fsummary>Determine if a term is a fun</fsummary>
<desc><p>Return true if <c>term</c> is a fun.</p></desc>
</func>
- <func><name><ret>int</ret><nametext>enif_is_identical(ErlNifEnv* env, ERL_NIF_TERM lhs, ERL_NIF_TERM rhs)</nametext></name>
+ <func><name><ret>int</ret><nametext>enif_is_identical(ERL_NIF_TERM lhs, ERL_NIF_TERM rhs)</nametext></name>
<fsummary>Erlang operator =:=</fsummary>
<desc><p>Return true if the two terms are identical. Corresponds to the
Erlang operators <c>=:=</c> and
@@ -590,19 +710,46 @@ typedef enum {
<fsummary>Determine if a term is a port</fsummary>
<desc><p>Return true if <c>term</c> is a port.</p></desc>
</func>
-
<func><name><ret>int</ret><nametext>enif_is_ref(ErlNifEnv* env, ERL_NIF_TERM term)</nametext></name>
<fsummary>Determine if a term is a reference</fsummary>
<desc><p>Return true if <c>term</c> is a reference.</p></desc>
</func>
+ <func><name><ret>int</ret><nametext>enif_is_tuple(ErlNifEnv* env, ERL_NIF_TERM term)</nametext></name>
+ <fsummary>Determine if a term is a tuple</fsummary>
+ <desc><p>Return true if <c>term</c> is a tuple.</p></desc>
+ </func>
+ <func><name><ret>int</ret><nametext>enif_is_list(ErlNifEnv* env, ERL_NIF_TERM term)</nametext></name>
+ <fsummary>Determine if a term is a list</fsummary>
+ <desc><p>Return true if <c>term</c> is a list.</p></desc>
+ </func>
+ <func><name><ret>int</ret><nametext>enif_keep_resource(void* obj)</nametext></name>
+ <fsummary>Add a reference to a resource object</fsummary>
+ <desc><p>Add a reference to resource object <c>obj</c> obtained from
+ <seealso marker="#enif_alloc_resource">enif_alloc_resource</seealso>.
+ Each call to <c>enif_keep_resource</c> for an object must be balanced by
+ a call to <seealso marker="#enif_release_resource">enif_release_resource</seealso>
+ before the object will be destructed.</p></desc>
+ </func>
<func><name><ret>ERL_NIF_TERM</ret><nametext>enif_make_atom(ErlNifEnv* env, const char* name)</nametext></name>
<fsummary>Create an atom term</fsummary>
- <desc><p>Create an atom term from the C-string <c>name</c>. Unlike other terms, atom
- terms may be saved and used between NIF calls.</p></desc>
+ <desc><p>Create an atom term from the null-terminated C-string <c>name</c>
+ with iso-latin-1 encoding.</p></desc>
+ </func>
+ <func><name><ret>ERL_NIF_TERM</ret><nametext>enif_make_atom_len(ErlNifEnv* env, const char* name, size_t len)</nametext></name>
+ <fsummary>Create an atom term</fsummary>
+ <desc><p>Create an atom term from the string <c>name</c> with length <c>len</c>.
+ Null-characters are treated as any other characters.</p></desc>
</func>
<func><name><ret>ERL_NIF_TERM</ret><nametext>enif_make_badarg(ErlNifEnv* env)</nametext></name>
<fsummary>Make a badarg exception.</fsummary>
- <desc><p>Make a badarg exception to be returned from a NIF.</p></desc>
+ <desc><p>Make a badarg exception to be returned from a NIF, and set
+ an associated exception reason in <c>env</c>. If
+ <c>enif_make_badarg</c> is called, the term it returns <em>must</em>
+ be returned from the function that called it. No other return value
+ is allowed. Also, the term returned from <c>enif_make_badarg</c> may
+ be passed only to
+ <seealso marker="#enif_is_exception">enif_is_exception</seealso> and
+ not to any other NIF API function.</p></desc>
</func>
<func><name><ret>ERL_NIF_TERM</ret><nametext>enif_make_binary(ErlNifEnv* env, ErlNifBinary* bin)</nametext></name>
<fsummary>Make a binary term.</fsummary>
@@ -611,21 +758,40 @@ typedef enum {
<c>bin</c> should be considered read-only for the rest of the NIF
call and then as released.</p></desc>
</func>
+ <func><name><ret>ERL_NIF_TERM</ret><nametext>enif_make_copy(ErlNifEnv* dst_env, ERL_NIF_TERM src_term)</nametext></name>
+ <fsummary>Make a copy of a term.</fsummary>
+ <desc><p>Make a copy of term <c>src_term</c>. The copy will be created in
+ environment <c>dst_env</c>. The source term may be located in any
+ environment.</p></desc>
+ </func>
<func><name><ret>ERL_NIF_TERM</ret><nametext>enif_make_double(ErlNifEnv* env, double d)</nametext></name>
- <fsummary>Create an floating-point term</fsummary>
- <desc><p>Create an floating-point term from a <c>double</c>.</p></desc>
+ <fsummary>Create a floating-point term</fsummary>
+ <desc><p>Create a floating-point term from a <c>double</c>.</p></desc>
</func>
- <func><name><ret>int</ret><nametext>enif_make_existing_atom(ErlNifEnv* env, const char* name, ERL_NIF_TERM* atom)</nametext></name>
+ <func><name><ret>int</ret><nametext>enif_make_existing_atom(ErlNifEnv* env, const char* name, ERL_NIF_TERM* atom, ErlNifCharEncoding encode)</nametext></name>
<fsummary>Create an existing atom term</fsummary>
<desc><p>Try to create the term of an already existing atom from
- the C-string <c>name</c>. If the atom already exist store the
- term in <c>*atom</c> and return true, otherwise return
- false.</p></desc>
+ the null-terminated C-string <c>name</c> with encoding
+ <seealso marker="#ErlNifCharEncoding">encode</seealso>. If the atom
+ already exists store the term in <c>*atom</c> and return true, otherwise
+ return false.</p></desc>
+ </func>
+ <func><name><ret>int</ret><nametext>enif_make_existing_atom_len(ErlNifEnv* env, const char* name, size_t len, ERL_NIF_TERM* atom, ErlNifCharEncoding encoding)</nametext></name>
+ <fsummary>Create an existing atom term</fsummary>
+ <desc><p>Try to create the term of an already existing atom from the
+ string <c>name</c> with length <c>len</c> and encoding
+ <seealso marker="#ErlNifCharEncoding">encode</seealso>. Null-characters
+ are treated as any other characters. If the atom already exists store the term
+ in <c>*atom</c> and return true, otherwise return false.</p></desc>
</func>
<func><name><ret>ERL_NIF_TERM</ret><nametext>enif_make_int(ErlNifEnv* env, int i)</nametext></name>
<fsummary>Create an integer term</fsummary>
<desc><p>Create an integer term.</p></desc>
</func>
+ <func><name><ret>ERL_NIF_TERM</ret><nametext>enif_make_int64(ErlNifEnv* env, ErlNifSInt64 i)</nametext></name>
+ <fsummary>Create an integer term</fsummary>
+ <desc><p>Create an integer term from a signed 64-bit integer.</p></desc>
+ </func>
<func><name><ret>ERL_NIF_TERM</ret><nametext>enif_make_list(ErlNifEnv* env, unsigned cnt, ...)</nametext></name>
<fsummary>Create a list term.</fsummary>
<desc><p>Create an ordinary list term of length <c>cnt</c>. Expects
@@ -644,7 +810,7 @@ typedef enum {
<fsummary>Create a list term.</fsummary>
<desc><p>Create an ordinary list term with length indicated by the
function name. Prefer these functions (macros) over the variadic
- <c>enif_make_list</c> to get compile time error if the number of
+ <c>enif_make_list</c> to get a compile time error if the number of
arguments does not match.</p></desc>
</func>
<func><name><ret>ERL_NIF_TERM</ret><nametext>enif_make_list_cell(ErlNifEnv* env, ERL_NIF_TERM head, ERL_NIF_TERM tail)</nametext></name>
@@ -660,6 +826,20 @@ typedef enum {
<fsummary>Create an integer term from a long int</fsummary>
<desc><p>Create an integer term from a <c>long int</c>.</p></desc>
</func>
+ <func><name><ret>unsigned char*</ret><nametext>enif_make_new_binary(ErlNifEnv* env, size_t size, ERL_NIF_TERM* termp)</nametext></name>
+ <fsummary>Allocate and create a new binary term</fsummary>
+ <desc><p>Allocate a binary of size <c>size</c> bytes and create an owning
+ term. The binary data is mutable until the calling NIF returns. This is a
+ quick way to create a new binary without having to use
+ <seealso marker="#ErlNifBinary">ErlNifBinary</seealso>. The drawbacks are
+ that the binary can not be kept between NIF calls and it can not be
+ reallocated.</p><p>Return a pointer to the raw binary data and set
+ <c>*termp</c> to the binary term.</p></desc>
+ </func>
+ <func><name><ret>ERL_NIF_TERM</ret><nametext>enif_make_pid(ErlNifEnv* env, const ErlNifPid* pid)</nametext></name>
+ <fsummary>Make a pid term</fsummary>
+ <desc><p>Make a pid term from <c>*pid</c>.</p></desc>
+ </func>
<func><name><ret>ERL_NIF_TERM</ret><nametext>enif_make_ref(ErlNifEnv* env)</nametext></name>
<fsummary>Create a reference.</fsummary>
<desc><p>Create a reference like <seealso marker="erlang#make_ref-0">erlang:make_ref/0</seealso>.</p></desc>
@@ -668,20 +848,50 @@ typedef enum {
<fsummary>Create an opaque handle to a resource object</fsummary>
<desc><p>Create an opaque handle to a memory managed resource object
obtained by <seealso marker="#enif_alloc_resource">enif_alloc_resource</seealso>.
- No ownership transfer is done, the resource object still needs to be released by
- <seealso marker="#enif_release_resource">enif_release_resource</seealso>.</p>
- <p>Note that the only defined behaviour when using of a resource term in
+ No ownership transfer is done, as the resource object still needs to be released by
+ <seealso marker="#enif_release_resource">enif_release_resource</seealso>,
+ but note that the call to <c>enif_release_resource</c> can occur
+ immediately after obtaining the term from <c>enif_make_resource</c>,
+ in which case the resource object will be deallocated when the
+ term is garbage collected. See the
+ <seealso marker="#enif_resource_example">example of creating and
+ returning a resource object</seealso> for more details.</p>
+ <p>Note that the only defined behaviour of using a resource term in
an Erlang program is to store it and send it between processes on the
same node. Other operations such as matching or <c>term_to_binary</c>
will have unpredictable (but harmless) results.</p></desc>
</func>
+ <func><name><ret>ERL_NIF_TERM</ret><nametext>enif_make_resource_binary(ErlNifEnv* env, void* obj, const void* data, size_t size)</nametext></name>
+ <fsummary>Create a custom binary term</fsummary>
+ <desc><p>Create a binary term that is memory managed by a resource object
+ <c>obj</c> obtained by <seealso marker="#enif_alloc_resource">enif_alloc_resource</seealso>.
+ The returned binary term will consist of <c>size</c> bytes pointed to
+ by <c>data</c>. This raw binary data must be kept readable and unchanged
+ until the destructor of the resource is called. The binary data may be
+ stored external to the resource object in which case it is the responsibility
+ of the destructor to release the data.</p>
+ <p>Several binary terms may be managed by the same resource object. The
+ destructor will not be called until the last binary is garbage collected.
+ This can be useful as a way to return different parts of a larger binary
+ buffer.</p>
+ <p>As with <seealso marker="#enif_make_resource">enif_make_resource</seealso>,
+ no ownership transfer is done. The resource still needs to be released with
+ <seealso marker="#enif_release_resource">enif_release_resource</seealso>.</p>
+ </desc>
+ </func>
<func><name><ret>ERL_NIF_TERM</ret><nametext>enif_make_string(ErlNifEnv* env, const char* string, ErlNifCharEncoding encoding)</nametext></name>
<fsummary>Create a string.</fsummary>
<desc><p>Create a list containing the characters of the
null-terminated string <c>string</c> with encoding <seealso marker="#ErlNifCharEncoding">encoding</seealso>.</p></desc>
</func>
+ <func><name><ret>ERL_NIF_TERM</ret><nametext>enif_make_string_len(ErlNifEnv* env, const char* string, size_t len, ErlNifCharEncoding encoding)</nametext></name>
+ <fsummary>Create a string.</fsummary>
+ <desc><p>Create a list containing the characters of the string <c>string</c> with
+ length <c>len</c> and encoding <seealso marker="#ErlNifCharEncoding">encoding</seealso>.
+ Null-characters are treated as any other characters.</p></desc>
+ </func>
<func><name><ret>ERL_NIF_TERM</ret><nametext>enif_make_sub_binary(ErlNifEnv*
- env, ERL_NIF_TERM bin_term, unsigned pos, unsigned size)</nametext></name>
+ env, ERL_NIF_TERM bin_term, size_t pos, size_t size)</nametext></name>
<fsummary>Make a subbinary term.</fsummary>
<desc><p>Make a subbinary of binary <c>bin_term</c>, starting at
zero-based position <c>pos</c> with a length of <c>size</c> bytes.
@@ -707,7 +917,7 @@ typedef enum {
<fsummary>Create a tuple term.</fsummary>
<desc><p>Create a tuple term with length indicated by the
function name. Prefer these functions (macros) over the variadic
- <c>enif_make_tuple</c> to get compile time error if the number of
+ <c>enif_make_tuple</c> to get a compile time error if the number of
arguments does not match.</p></desc>
</func>
<func><name><ret>ERL_NIF_TERM</ret><nametext>enif_make_tuple_from_array(ErlNifEnv* env, const ERL_NIF_TERM arr[], unsigned cnt)</nametext></name>
@@ -719,36 +929,41 @@ typedef enum {
<fsummary>Create an unsigned integer term</fsummary>
<desc><p>Create an integer term from an <c>unsigned int</c>.</p></desc>
</func>
+ <func><name><ret>ERL_NIF_TERM</ret><nametext>enif_make_uint64(ErlNifEnv* env, ErlNifUInt64 i)</nametext></name>
+ <fsummary>Create an unsigned integer term</fsummary>
+ <desc><p>Create an integer term from an unsigned 64-bit integer.</p></desc>
+ </func>
<func><name><ret>ERL_NIF_TERM</ret><nametext>enif_make_ulong(ErlNifEnv* env, unsigned long i)</nametext></name>
<fsummary>Create an integer term from an unsigned long int</fsummary>
<desc><p>Create an integer term from an <c>unsigned long int</c>.</p></desc>
</func>
<func><name><ret>ErlNifMutex*</ret><nametext>enif_mutex_create(char *name)</nametext></name>
<fsummary></fsummary>
- <desc><p>Same as <seealso marker="erl_driver#erl_drv_mutex_create">erl_drv_mutex_create()</seealso>.
+ <desc><p>Same as <seealso marker="erl_driver#erl_drv_mutex_create">erl_drv_mutex_create</seealso>.
</p></desc>
</func>
<func><name><ret>void</ret><nametext>enif_mutex_destroy(ErlNifMutex *mtx)</nametext></name>
<fsummary></fsummary>
- <desc><p>Same as <seealso marker="erl_driver#erl_drv_mutex_destroy">erl_drv_mutex_destroy()</seealso>.
+ <desc><p>Same as <seealso marker="erl_driver#erl_drv_mutex_destroy">erl_drv_mutex_destroy</seealso>.
</p></desc>
</func>
<func><name><ret>void</ret><nametext>enif_mutex_lock(ErlNifMutex *mtx)</nametext></name>
<fsummary></fsummary>
- <desc><p>Same as <seealso marker="erl_driver#erl_drv_mutex_lock">erl_drv_mutex_lock()</seealso>.
+ <desc><p>Same as <seealso marker="erl_driver#erl_drv_mutex_lock">erl_drv_mutex_lock</seealso>.
</p></desc>
</func>
<func><name><ret>int</ret><nametext>enif_mutex_trylock(ErlNifMutex *mtx)</nametext></name>
<fsummary></fsummary>
- <desc><p>Same as <seealso marker="erl_driver#erl_drv_mutex_trylock">erl_drv_mutex_trylock()</seealso>.
+ <desc><p>Same as <seealso marker="erl_driver#erl_drv_mutex_trylock">erl_drv_mutex_trylock</seealso>.
</p></desc>
</func>
<func><name><ret>void</ret><nametext>enif_mutex_unlock(ErlNifMutex *mtx)</nametext></name>
<fsummary></fsummary>
- <desc><p>Same as <seealso marker="erl_driver#erl_drv_mutex_unlock">erl_drv_mutex_unlock()</seealso>.
+ <desc><p>Same as <seealso marker="erl_driver#erl_drv_mutex_unlock">erl_drv_mutex_unlock</seealso>.
</p></desc>
</func>
- <func><name><ret>ErlNifResourceType*</ret><nametext>enif_open_resource_type(ErlNifEnv* env, const char* name,
+ <func><name><ret>ErlNifResourceType*</ret><nametext>enif_open_resource_type(ErlNifEnv* env,
+ const char* module_str, const char* name,
ErlNifResourceDtor* dtor, ErlNifResourceFlags flags, ErlNifResourceFlags* tried)</nametext></name>
<fsummary>Create or takeover a resource type</fsummary>
<desc><p>Create or takeover a resource type identified by the string
@@ -762,10 +977,10 @@ typedef enum {
The supplied destructor <c>dtor</c> will be called both for existing instances
as well as new instances not yet created by the calling NIF library.</item>
</taglist>
- <p>The two flag values can be combined with bitwise-or. To avoid unintentionally
- name clashes a good practice is to include the module name as part of the
- type <c>name</c>. The <c>dtor</c> may be <c>NULL</c> in case no destructor
- is needed.</p>
+ <p>The two flag values can be combined with bitwise-or. The name of the
+ resource type is local to the calling module. Argument <c>module_str</c>
+ is not (yet) used and must be NULL. The <c>dtor</c> may be <c>NULL</c>
+ in case no destructor is needed.</p>
<p>On success, return a pointer to the resource type and <c>*tried</c>
will be set to either <c>ERL_NIF_RT_CREATE</c> or
<c>ERL_NIF_RT_TAKEOVER</c> to indicate what was actually done.
@@ -782,129 +997,163 @@ typedef enum {
<c>reload</c> or <c>upgrade</c>.</p>
<p>Was previously named <c>enif_get_data</c>.</p></desc>
</func>
- <func><name><ret>void</ret><nametext>enif_realloc_binary(ErlNifEnv* env, ErlNifBinary* bin, unsigned size)</nametext></name>
+ <func><name><ret>int</ret><nametext>enif_realloc_binary(ErlNifBinary* bin, size_t size)</nametext></name>
<fsummary>Change the size of a binary.</fsummary>
<desc><p>Change the size of a binary <c>bin</c>. The source binary
may be read-only, in which case it will be left untouched and
- a mutable copy is allocated and assigned to <c>*bin</c>.</p></desc>
+ a mutable copy is allocated and assigned to <c>*bin</c>. Return true on success,
+ false if memory allocation failed.</p></desc>
</func>
- <func><name><ret>void</ret><nametext>enif_release_binary(ErlNifEnv* env, ErlNifBinary* bin)</nametext></name>
+ <func><name><ret>void</ret><nametext>enif_release_binary(ErlNifBinary* bin)</nametext></name>
<fsummary>Release a binary.</fsummary>
- <desc><p>Release a binary obtained
- from <c>enif_alloc_binary</c>.</p></desc>
+ <desc><p>Release a binary obtained from <c>enif_alloc_binary</c>.</p></desc>
</func>
- <func><name><ret>void</ret><nametext>enif_release_resource(ErlNifEnv* env, void* obj)</nametext></name>
+ <func><name><ret>void</ret><nametext>enif_release_resource(void* obj)</nametext></name>
<fsummary>Release a resource object.</fsummary>
- <desc><p>Release a resource objects obtained from <c>enif_alloc_resource</c>.
- The object may still be alive if it is referred to by Erlang terms. Each call to
- <c>enif_release_resource</c> must correspond to a previous call to <c>enif_alloc_resource</c>.
- References made by <c>enif_make_resource</c> can only be released by the garbage collector.</p></desc>
+ <desc><p>Remove a reference to resource object <c>obj</c>obtained from
+ <seealso marker="#enif_alloc_resource">enif_alloc_resource</seealso>.
+ The resource object will be destructed when the last reference is removed.
+ Each call to <c>enif_release_resource</c> must correspond to a previous
+ call to <c>enif_alloc_resource</c> or
+ <seealso marker="#enif_keep_resource">enif_keep_resource</seealso>.
+ References made by <seealso marker="#enif_make_resource">enif_make_resource</seealso>
+ can only be removed by the garbage collector.</p></desc>
</func>
<func><name><ret>ErlNifRWLock*</ret><nametext>enif_rwlock_create(char *name)</nametext></name>
<fsummary></fsummary>
- <desc><p>Same as <seealso marker="erl_driver#erl_drv_rwlock_create">erl_drv_rwlock_create()</seealso>.
+ <desc><p>Same as <seealso marker="erl_driver#erl_drv_rwlock_create">erl_drv_rwlock_create</seealso>.
</p></desc>
</func>
<func><name><ret>void</ret><nametext>enif_rwlock_destroy(ErlNifRWLock *rwlck)</nametext></name>
<fsummary></fsummary>
- <desc><p>Same as <seealso marker="erl_driver#erl_drv_rwlock_destroy">erl_drv_rwlock_destroy()</seealso>.
+ <desc><p>Same as <seealso marker="erl_driver#erl_drv_rwlock_destroy">erl_drv_rwlock_destroy</seealso>.
</p></desc>
</func>
<func><name><ret>void</ret><nametext>enif_rwlock_rlock(ErlNifRWLock *rwlck)</nametext></name>
<fsummary></fsummary>
- <desc><p>Same as <seealso marker="erl_driver#erl_drv_rwlock_rlock">erl_drv_rwlock_rlock()</seealso>.
+ <desc><p>Same as <seealso marker="erl_driver#erl_drv_rwlock_rlock">erl_drv_rwlock_rlock</seealso>.
</p></desc>
</func>
<func><name><ret>void</ret><nametext>enif_rwlock_runlock(ErlNifRWLock *rwlck)</nametext></name>
<fsummary></fsummary>
- <desc><p>Same as <seealso marker="erl_driver#erl_drv_rwlock_runlock">erl_drv_rwlock_runlock()</seealso>.
+ <desc><p>Same as <seealso marker="erl_driver#erl_drv_rwlock_runlock">erl_drv_rwlock_runlock</seealso>.
</p></desc>
</func>
<func><name><ret>void</ret><nametext>enif_rwlock_rwlock(ErlNifRWLock *rwlck)</nametext></name>
<fsummary></fsummary>
- <desc><p>Same as <seealso marker="erl_driver#erl_drv_rwlock_rwlock">erl_drv_rwlock_rwlock()</seealso>.
+ <desc><p>Same as <seealso marker="erl_driver#erl_drv_rwlock_rwlock">erl_drv_rwlock_rwlock</seealso>.
</p></desc>
</func>
<func><name><ret>void</ret><nametext>enif_rwlock_rwunlock(ErlNifRWLock *rwlck)</nametext></name>
<fsummary></fsummary>
- <desc><p>Same as <seealso marker="erl_driver#erl_drv_rwlock_rwunlock">erl_drv_rwlock_rwunlock()</seealso>.
+ <desc><p>Same as <seealso marker="erl_driver#erl_drv_rwlock_rwunlock">erl_drv_rwlock_rwunlock</seealso>.
</p></desc>
</func>
<func><name><ret>int</ret><nametext>enif_rwlock_tryrlock(ErlNifRWLock *rwlck)</nametext></name>
<fsummary></fsummary>
- <desc><p>Same as <seealso marker="erl_driver#erl_drv_rwlock_tryrlock">erl_drv_rwlock_tryrlock()</seealso>.
+ <desc><p>Same as <seealso marker="erl_driver#erl_drv_rwlock_tryrlock">erl_drv_rwlock_tryrlock</seealso>.
</p></desc>
</func>
<func><name><ret>int</ret><nametext>enif_rwlock_tryrwlock(ErlNifRWLock *rwlck)</nametext></name>
<fsummary></fsummary>
- <desc><p>Same as <seealso marker="erl_driver#erl_drv_rwlock_tryrwlock">erl_drv_rwlock_tryrwlock()</seealso>.
+ <desc><p>Same as <seealso marker="erl_driver#erl_drv_rwlock_tryrwlock">erl_drv_rwlock_tryrwlock</seealso>.
</p></desc>
</func>
- <func><name><ret>unsigned</ret><nametext>enif_sizeof_resource(ErlNifEnv* env, void* obj)</nametext></name>
+ <func><name><ret>ErlNifPid*</ret><nametext>enif_self(ErlNifEnv* caller_env, ErlNifPid* pid)</nametext></name>
+ <fsummary>Get the pid of the calling process.</fsummary>
+ <desc><p>Initialize the pid variable <c>*pid</c> to represent the
+ calling process. Return <c>pid</c>.</p></desc>
+ </func>
+ <func><name><ret>int</ret><nametext>enif_send(ErlNifEnv* env, ErlNifPid* to_pid, ErlNifEnv* msg_env, ERL_NIF_TERM msg)</nametext></name>
+ <fsummary>Send a message to a process.</fsummary>
+ <desc><p>Send a message to a process.</p>
+ <taglist>
+ <tag><c>env</c></tag>
+ <item>The environment of the calling process. Must be NULL if and
+ only if calling from a created thread.</item>
+ <tag><c>*to_pid</c></tag>
+ <item>The pid of the receiving process. The pid should refer to a process on the local node.</item>
+ <tag><c>msg_env</c></tag>
+ <item>The environment of the message term. Must be a process
+ independent environment allocated with
+ <seealso marker="#enif_alloc_env">enif_alloc_env</seealso>.</item>
+ <tag><c>msg</c></tag>
+ <item>The message term to send.</item>
+ </taglist>
+ <p>Return true on success, or false if <c>*to_pid</c> does not refer to an alive local process.</p>
+ <p>The message environment <c>msg_env</c> with all its terms (including
+ <c>msg</c>) will be invalidated by a successful call to <c>enif_send</c>. The environment
+ should either be freed with <seealso marker="#enif_free_env">enif_free_env</seealso>
+ of cleared for reuse with <seealso marker="#enif_clear_env">enif_clear_env</seealso>.</p>
+ <p>This function is only thread-safe when the emulator with SMP support is used.
+ It can only be used in a non-SMP emulator from a NIF-calling thread.</p>
+ </desc>
+ </func>
+ <func><name><ret>unsigned</ret><nametext>enif_sizeof_resource(void* obj)</nametext></name>
<fsummary>Get the byte size of a resource object</fsummary>
<desc><p>Get the byte size of a resource object <c>obj</c> obtained by
- <c>enif_alloc_resource</c>.</p></desc>
+ <seealso marker="#enif_alloc_resource">enif_alloc_resource</seealso>.</p></desc>
</func>
<func>
<name><ret>void</ret><nametext>enif_system_info(ErlNifSysInfo *sys_info_ptr, size_t size)</nametext></name>
<fsummary>Get information about the Erlang runtime system</fsummary>
- <desc><p>Same as <seealso marker="erl_driver#driver_system_info">driver_system_info()</seealso>.
+ <desc><p>Same as <seealso marker="erl_driver#driver_system_info">driver_system_info</seealso>.
</p></desc>
</func>
<func><name><ret>int</ret><nametext>enif_thread_create(char *name,ErlNifTid *tid,void * (*func)(void *),void *args,ErlNifThreadOpts *opts)</nametext></name>
<fsummary></fsummary>
- <desc><p>Same as <seealso marker="erl_driver#erl_drv_thread_create">erl_drv_thread_create()</seealso>.
+ <desc><p>Same as <seealso marker="erl_driver#erl_drv_thread_create">erl_drv_thread_create</seealso>.
</p></desc>
</func>
<func><name><ret>void</ret><nametext>enif_thread_exit(void *resp)</nametext></name>
<fsummary></fsummary>
- <desc><p>Same as <seealso marker="erl_driver#erl_drv_thread_exit">erl_drv_thread_exit()</seealso>.
+ <desc><p>Same as <seealso marker="erl_driver#erl_drv_thread_exit">erl_drv_thread_exit</seealso>.
</p></desc>
</func>
<func><name><ret>int</ret><nametext>enif_thread_join(ErlNifTid, void **respp)</nametext></name>
<fsummary></fsummary>
- <desc><p>Same as <seealso marker="erl_driver#erl_drv_thread_join">erl_drv_thread_join ()</seealso>.
+ <desc><p>Same as <seealso marker="erl_driver#erl_drv_thread_join">erl_drv_thread_join </seealso>.
</p></desc>
</func>
<func><name><ret>ErlNifThreadOpts*</ret><nametext>enif_thread_opts_create(char *name)</nametext></name>
<fsummary></fsummary>
- <desc><p>Same as <seealso marker="erl_driver#erl_drv_thread_opts_create">erl_drv_thread_opts_create()</seealso>.
+ <desc><p>Same as <seealso marker="erl_driver#erl_drv_thread_opts_create">erl_drv_thread_opts_create</seealso>.
</p></desc>
</func>
<func><name><ret>void</ret><nametext>enif_thread_opts_destroy(ErlNifThreadOpts *opts)</nametext></name>
<fsummary></fsummary>
- <desc><p>Same as <seealso marker="erl_driver#erl_drv_thread_opts_destroy">erl_drv_thread_opts_destroy()</seealso>.
+ <desc><p>Same as <seealso marker="erl_driver#erl_drv_thread_opts_destroy">erl_drv_thread_opts_destroy</seealso>.
</p></desc>
</func>
<func><name><ret>ErlNifTid</ret><nametext>enif_thread_self(void)</nametext></name>
<fsummary></fsummary>
- <desc><p>Same as <seealso marker="erl_driver#erl_drv_thread_self">erl_drv_thread_self()</seealso>.
+ <desc><p>Same as <seealso marker="erl_driver#erl_drv_thread_self">erl_drv_thread_self</seealso>.
</p></desc>
</func>
<func><name><ret>int</ret><nametext>enif_tsd_key_create(char *name, ErlNifTSDKey *key)</nametext></name>
<fsummary></fsummary>
- <desc><p>Same as <seealso marker="erl_driver#erl_drv_tsd_key_create">erl_drv_tsd_key_create()</seealso>.
+ <desc><p>Same as <seealso marker="erl_driver#erl_drv_tsd_key_create">erl_drv_tsd_key_create</seealso>.
</p></desc>
</func>
<func><name><ret>void</ret><nametext>enif_tsd_key_destroy(ErlNifTSDKey key)</nametext></name>
<fsummary></fsummary>
- <desc><p>Same as <seealso marker="erl_driver#erl_drv_tsd_key_destroy">erl_drv_tsd_key_destroy()</seealso>.
+ <desc><p>Same as <seealso marker="erl_driver#erl_drv_tsd_key_destroy">erl_drv_tsd_key_destroy</seealso>.
</p></desc>
</func>
<func><name><ret>void*</ret><nametext>enif_tsd_get(ErlNifTSDKey key)</nametext></name>
<fsummary></fsummary>
- <desc><p>Same as <seealso marker="erl_driver#erl_drv_tsd_get">erl_drv_tsd_get()</seealso>.
+ <desc><p>Same as <seealso marker="erl_driver#erl_drv_tsd_get">erl_drv_tsd_get</seealso>.
</p></desc>
</func>
<func><name><ret>void</ret><nametext>enif_tsd_set(ErlNifTSDKey key, void *data)</nametext></name>
<fsummary></fsummary>
- <desc><p>Same as <seealso marker="erl_driver#erl_drv_tsd_set">erl_drv_tsd_set()</seealso>.
+ <desc><p>Same as <seealso marker="erl_driver#erl_drv_tsd_set">erl_drv_tsd_set</seealso>.
</p></desc>
</func>
</funcs>
<section>
<title>SEE ALSO</title>
- <p><seealso marker="erlang#load_nif-2">load_nif(3)</seealso></p>
+ <p><seealso marker="erlang#load_nif-2">erlang:load_nif/2</seealso></p>
</section>
</cref>
diff --git a/erts/doc/src/erl_prim_loader.xml b/erts/doc/src/erl_prim_loader.xml
index ccaa9b725f..9f5b3f385b 100644
--- a/erts/doc/src/erl_prim_loader.xml
+++ b/erts/doc/src/erl_prim_loader.xml
@@ -4,7 +4,7 @@
<erlref>
<header>
<copyright>
- <year>1996</year><year>2009</year>
+ <year>1996</year><year>2011</year>
<holder>Ericsson AB. All Rights Reserved.</holder>
</copyright>
<legalnotice>
@@ -55,33 +55,31 @@
<c>-loader_debug</c> are also experimental</p></warning>
</description>
+ <datatypes>
+ <datatype>
+ <name name="host"/>
+ </datatype>
+ </datatypes>
+
<funcs>
<func>
- <name>start(Id, Loader, Hosts) -> {ok, Pid} | {error, What}</name>
+ <name name="start" arity="3"/>
<fsummary>Start the Erlang low level loader</fsummary>
- <type>
- <v>Id = term()</v>
- <v>Loader = atom() | string()</v>
- <v>Hosts = [Host]</v>
- <v>Host = atom()</v>
- <v>Pid = pid()</v>
- <v>What = term()</v>
- </type>
<desc>
<p>Starts the Erlang low level loader. This function is called
by the <c>init</c> process (and module). The <c>init</c>
- process reads the command line flags <c>-id Id</c>,
- <c>-loader Loader</c>, and <c>-hosts Hosts</c>. These are
+ process reads the command line flags <c>-id <anno>Id</anno></c>,
+ <c>-loader <anno>Loader</anno></c>, and <c>-hosts <anno>Hosts</anno></c>. These are
the arguments supplied to the <c>start/3</c> function.</p>
<p>If <c>-loader</c> is not given, the default loader is
<c>efile</c> which tells the system to read from the file
system.</p>
- <p>If <c>-loader</c> is <c>inet</c>, the <c>-id Id</c>,
- <c>-hosts Hosts</c>, and <c>-setcookie Cookie</c> flags must
- also be supplied. <c>Hosts</c> identifies hosts which this
+ <p>If <c>-loader</c> is <c>inet</c>, the <c>-id <anno>Id</anno></c>,
+ <c>-hosts <anno>Hosts</anno></c>, and <c>-setcookie Cookie</c> flags must
+ also be supplied. <c><anno>Hosts</anno></c> identifies hosts which this
node can contact in order to load modules. One Erlang
runtime system with a <c>erl_boot_server</c> process must be
- started on each of hosts given in <c>Hosts</c> in order to
+ started on each of hosts given in <c><anno>Hosts</anno></c> in order to
answer the requests. See <seealso
marker="kernel:erl_boot_server">erl_boot_server(3)</seealso>.</p>
<p>If <c>-loader</c> is something else, the given port program
@@ -90,35 +88,26 @@
</desc>
</func>
<func>
- <name>get_file(Filename) -> {ok, Bin, FullName} | error</name>
+ <name name="get_file" arity="1"/>
<fsummary>Get a file</fsummary>
- <type>
- <v>Filename = string()</v>
- <v>Bin = binary()</v>
- <v>FullName = string()</v>
- </type>
<desc>
<p>This function fetches a file using the low level loader.
- <c>Filename</c> is either an absolute file name or just the name
+ <c><anno>Filename</anno></c> is either an absolute file name or just the name
of the file, for example <c>"lists.beam"</c>. If an internal
path is set to the loader, this path is used to find the file.
If a user supplied loader is used, the path can be stripped
off if it is obsolete, and the loader does not use a path.
- <c>FullName</c> is the complete name of the fetched file.
- <c>Bin</c> is the contents of the file as a binary.</p>
+ <c><anno>FullName</anno></c> is the complete name of the fetched file.
+ <c><anno>Bin</anno></c> is the contents of the file as a binary.</p>
- <p>The <c>Filename</c> can also be a file in an archive. For example
- <c>/otp/root/lib/mnesia-4.4.7.ez/mnesia-4.4.7/ebin/mnesia_backup.beam</c>
+ <p>The <c><anno>Filename</anno></c> can also be a file in an archive. For example
+ <c>$OTPROOT/lib/</c><c>mnesia-4.4.7.ez/mnesia-4.4.7/ebin/</c><c>mnesia.beam</c>.
See <seealso marker="kernel:code">code(3)</seealso> about archive files.</p>
</desc>
</func>
<func>
- <name>get_path() -> {ok, Path}</name>
+ <name name="get_path" arity="0"/>
<fsummary>Get the path set in the loader</fsummary>
- <type>
- <v>Path = [Dir]</v>
- <v>Dir = string()</v>
- </type>
<desc>
<p>This function gets the path set in the loader. The path is
set by the <c>init</c> process according to information found
@@ -126,35 +115,26 @@
</desc>
</func>
<func>
- <name>list_dir(Dir) -> {ok, Filenames} | error</name>
+ <name name="list_dir" arity="1"/>
<fsummary>List files in a directory</fsummary>
- <type>
- <v>Dir = name()</v>
- <v>Filenames = [Filename]</v>
- <v>Filename = string()</v>
- </type>
<desc>
<p>Lists all the files in a directory. Returns
- <c>{ok, Filenames}</c> if successful. Otherwise, it returns
- <c>error</c>. <c>Filenames</c> is a list of
+ <c>{ok, <anno>Filenames</anno>}</c> if successful. Otherwise, it returns
+ <c>error</c>. <c><anno>Filenames</anno></c> is a list of
the names of all the files in the directory. The names are
not sorted.</p>
- <p>The <c>Dir</c> can also be a directory in an archive. For example
- <c>/otp/root/lib/mnesia-4.4.7.ez/mnesia-4.4.7/ebin</c>
+ <p>The <c><anno>Dir</anno></c> can also be a directory in an archive. For example
+ <c>$OTPROOT/lib/</c><c>mnesia-4.4.7.ez/mnesia-4.4.7/ebin</c>.
See <seealso marker="kernel:code">code(3)</seealso> about archive files.</p>
</desc>
</func>
<func>
- <name>read_file_info(Filename) -> {ok, FileInfo} | error</name>
+ <name name="read_file_info" arity="1"/>
<fsummary>Get information about a file</fsummary>
- <type>
- <v>Filename = name()</v>
- <v>FileInfo = #file_info{}</v>
- </type>
<desc>
<p>Retrieves information about a file. Returns
- <c>{ok, FileInfo}</c> if successful, otherwise
- <c>error</c>. <c>FileInfo</c> is a record
+ <c>{ok, <anno>FileInfo</anno>}</c> if successful, otherwise
+ <c>error</c>. <c><anno>FileInfo</anno></c> is a record
<c>file_info</c>, defined in the Kernel include file
<c>file.hrl</c>. Include the following directive in the module
from which the function is called:</p>
@@ -162,18 +142,14 @@
-include_lib("kernel/include/file.hrl").</code>
<p>See <seealso marker="kernel:file">file(3)</seealso> for more info about
the record <c>file_info</c>.</p>
- <p>The <c>Filename</c> can also be a file in an archive. For example
- <c>/otp/root/lib/mnesia-4.4.7.ez/mnesia-4.4.7/ebin/mnesia_backup.beam</c>
+ <p>The <c><anno>Filename</anno></c> can also be a file in an archive. For example
+ <c>$OTPROOT/lib/</c><c>mnesia-4.4.7.ez/mnesia-4.4.7/ebin/</c><c>mnesia</c>.
See <seealso marker="kernel:code">code(3)</seealso> about archive files.</p>
</desc>
</func>
<func>
- <name>set_path(Path) -> ok</name>
+ <name name="set_path" arity="1"/>
<fsummary>Set the path of the loader</fsummary>
- <type>
- <v>Path = [Dir]</v>
- <v>Dir = string()</v>
- </type>
<desc>
<p>This function sets the path of the loader if <c>init</c>
interprets a <c>path</c> command in the start script.</p>
diff --git a/erts/doc/src/erlang.xml b/erts/doc/src/erlang.xml
index 46f8df4683..aef31f5b98 100644
--- a/erts/doc/src/erlang.xml
+++ b/erts/doc/src/erlang.xml
@@ -4,7 +4,7 @@
<erlref>
<header>
<copyright>
- <year>1996</year><year>2010</year>
+ <year>1996</year><year>2011</year>
<holder>Ericsson AB. All Rights Reserved.</holder>
</copyright>
<legalnotice>
@@ -48,22 +48,24 @@
"Allowed in guard tests".</p>
</description>
- <section>
- <title>DATA TYPES</title>
- <marker id="iolist_definition"></marker>
- <code type="none">
-ext_binary()
- a binary data object,
- structured according to the Erlang external term format
-
-iodata() = iolist() | binary()
+ <datatypes>
+ <datatype>
+ <name><marker id="type-ext_binary">ext_binary()</marker></name>
+ <desc>
+ <p>A binary data object, structured according to
+ the Erlang external term format.</p>
+ </desc>
+ </datatype>
+ <datatype>
+ <name name="timestamp"></name>
+ <desc><p>See <seealso marker="#now/0">now/0</seealso>.</p>
+ </desc>
+ </datatype>
+ </datatypes>
-iolist() = [char() | binary() | iolist()]
- a binary is allowed as the tail of the list</code>
- </section>
<funcs>
<func>
- <name>abs(Number) -> int() | float()</name>
+ <name>abs(Number) -> integer() | float()</name>
<fsummary>Arithmetical absolute value</fsummary>
<type>
<v>Number = number()</v>
@@ -80,7 +82,7 @@ iolist() = [char() | binary() | iolist()]
</desc>
</func>
<func>
- <name>adler32(Data) -> int()</name>
+ <name>erlang:adler32(Data) -> integer()</name>
<fsummary>Compute adler32 checksum</fsummary>
<type>
<v>Data = iodata()</v>
@@ -90,10 +92,10 @@ iolist() = [char() | binary() | iolist()]
</desc>
</func>
<func>
- <name>adler32(OldAdler, Data) -> int()</name>
+ <name>erlang:adler32(OldAdler, Data) -> integer()</name>
<fsummary>Compute adler32 checksum</fsummary>
<type>
- <v>OldAdler = int()</v>
+ <v>OldAdler = integer()</v>
<v>Data = iodata()</v>
</type>
<desc>
@@ -102,21 +104,21 @@ iolist() = [char() | binary() | iolist()]
<c>Data</c>.</p>
<p>The following code:</p>
<code>
- X = adler32(Data1),
- Y = adler32(X,Data2).
+ X = erlang:adler32(Data1),
+ Y = erlang:adler32(X,Data2).
</code>
<p>- would assign the same value to <c>Y</c> as this would:</p>
<code>
- Y = adler32([Data1,Data2]).
+ Y = erlang:adler32([Data1,Data2]).
</code>
</desc>
</func>
<func>
- <name>adler32_combine(FirstAdler, SecondAdler, SecondSize) -> int()</name>
+ <name>erlang:adler32_combine(FirstAdler, SecondAdler, SecondSize) -> integer()</name>
<fsummary>Combine two adler32 checksums</fsummary>
<type>
- <v>FirstAdler = SecondAdler = int()</v>
- <v>SecondSize = int()</v>
+ <v>FirstAdler = SecondAdler = integer()</v>
+ <v>SecondSize = integer()</v>
</type>
<desc>
<p>Combines two previously computed adler32 checksums.
@@ -124,14 +126,14 @@ iolist() = [char() | binary() | iolist()]
the second checksum to be known.</p>
<p>The following code:</p>
<code>
- Y = adler32(Data1),
- Z = adler32(Y,Data2).
+ Y = erlang:adler32(Data1),
+ Z = erlang:adler32(Y,Data2).
</code>
<p>- would assign the same value to <c>Z</c> as this would:</p>
<code>
- X = adler32(Data1),
- Y = adler32(Data2),
- Z = adler32_combine(X,Y,iolist_size(Data2)).
+ X = erlang:adler32(Data1),
+ Y = erlang:adler32(Data2),
+ Z = erlang:adler32_combine(X,Y,iolist_size(Data2)).
</code>
</desc>
</func>
@@ -147,7 +149,7 @@ iolist() = [char() | binary() | iolist()]
<c>Tuple1</c>, and contains the elements in <c>Tuple1</c>
followed by <c>Term</c> as the last element. Semantically
equivalent to
- <c>list_to_tuple(tuple_to_list(Tuple ++ [Term])</c>, but much
+ <c>list_to_tuple(tuple_to_list(Tuple) ++ [Term])</c>, but much
faster.</p>
<pre>
> <input>erlang:append_element({one, two}, three).</input>
@@ -155,20 +157,16 @@ iolist() = [char() | binary() | iolist()]
</desc>
</func>
<func>
- <name>apply(Fun, Args) -> term() | empty()</name>
+ <name name="apply" arity="2"/>
<fsummary>Apply a function to an argument list</fsummary>
- <type>
- <v>Fun = fun()</v>
- <v>Args = [term()]</v>
- </type>
<desc>
- <p>Call a fun, passing the elements in <c>Args</c> as
+ <p>Call a fun, passing the elements in <c><anno>Args</anno></c> as
arguments.</p>
<p>Note: If the number of elements in the arguments are known at
compile-time, the call is better written as
- <c>Fun(Arg1, Arg2, ... ArgN)</c>.</p>
+ <c><anno>Fun</anno>(Arg1, Arg2, ... ArgN)</c>.</p>
<warning>
- <p>Earlier, <c>Fun</c> could also be given as
+ <p>Earlier, <c><anno>Fun</anno></c> could also be given as
<c>{Module, Function}</c>, equivalent to
<c>apply(Module, Function, Args)</c>. This usage is
deprecated and will stop working in a future release of
@@ -177,15 +175,11 @@ iolist() = [char() | binary() | iolist()]
</desc>
</func>
<func>
- <name>apply(Module, Function, Args) -> term() | empty()</name>
+ <name name="apply" arity="3"/>
<fsummary>Apply a function to an argument list</fsummary>
- <type>
- <v>Module = Function = atom()</v>
- <v>Args = [term()]</v>
- </type>
<desc>
<p>Returns the result of applying <c>Function</c> in
- <c>Module</c> to <c>Args</c>. The applied function must
+ <c><anno>Module</anno></c> to <c><anno>Args</anno></c>. The applied function must
be exported from <c>Module</c>. The arity of the function is
the length of <c>Args</c>.</p>
<pre>
@@ -198,7 +192,7 @@ iolist() = [char() | binary() | iolist()]
"Erlang"</pre>
<p>Note: If the number of arguments are known at compile-time,
the call is better written as
- <c>Module:Function(Arg1, Arg2, ..., ArgN)</c>.</p>
+ <c><anno>Module</anno>:<anno>Function</anno>(Arg1, Arg2, ..., ArgN)</c>.</p>
<p>Failure: <c>error_handler:undefined_function/3</c> is called
if the applied function is not exported. The error handler
can be redefined (see
@@ -253,6 +247,54 @@ iolist() = [char() | binary() | iolist()]
</desc>
</func>
<func>
+ <name>binary_part(Subject, PosLen) -> binary()</name>
+ <fsummary>Extracts a part of a binary</fsummary>
+ <type>
+ <v>Subject = binary()</v>
+ <v>PosLen = {Start,Length}</v>
+ <v>Start = integer() >= 0</v>
+ <v>Length = integer() >= 0</v>
+ </type>
+ <desc>
+ <p>Extracts the part of the binary described by <c>PosLen</c>.</p>
+
+ <p>Negative length can be used to extract bytes at the end of a binary:</p>
+
+<code>
+1> Bin = &lt;&lt;1,2,3,4,5,6,7,8,9,10&gt;&gt;.
+2> binary_part(Bin,{byte_size(Bin), -5)).
+&lt;&lt;6,7,8,9,10&gt;&gt;
+</code>
+
+ <p>If <c>PosLen</c> in any way references outside the binary, a <c>badarg</c> exception is raised.</p>
+
+ <p><c>Start</c> is zero-based, i.e:</p>
+<code>
+1> Bin = &lt;&lt;1,2,3&gt;&gt;
+2> binary_part(Bin,{0,2}).
+&lt;&lt;1,2&gt;&gt;
+</code>
+
+ <p>See the STDLIB module <c>binary</c> for details about the <c>PosLen</c> semantics.</p>
+
+ <p>Allowed in guard tests.</p>
+ </desc>
+ </func>
+ <func>
+ <name>binary_part(Subject, Start, Length) -> binary()</name>
+ <fsummary>Extracts a part of a binary</fsummary>
+ <type>
+ <v>Subject = binary()</v>
+ <v>Start = integer() >= 0</v>
+ <v>Length = integer() >= 0</v>
+ </type>
+ <desc>
+ <p>The same as <c>binary_part(Subject, {Pos, Len})</c>.</p>
+
+ <p>Allowed in guard tests.</p>
+ </desc>
+ </func>
+ <func>
<name>binary_to_atom(Binary, Encoding) -> atom()</name>
<fsummary>Convert from text representation to an atom</fsummary>
<type>
@@ -318,6 +360,11 @@ iolist() = [char() | binary() | iolist()]
corresponding to the bytes from position <c>Start</c> to
position <c>Stop</c> in <c>Binary</c>. Positions in the
binary are numbered starting from 1.</p>
+
+ <note><p>This function's indexing style of using one-based indices for
+ binaries is deprecated. New code should use the functions in
+ the STDLIB module <c>binary</c> instead. They consequently
+ use the same (zero-based) style of indexing.</p></note>
</desc>
</func>
<func>
@@ -337,7 +384,7 @@ iolist() = [char() | binary() | iolist()]
<name>binary_to_term(Binary) -> term()</name>
<fsummary>Decode an Erlang external term format binary</fsummary>
<type>
- <v>Binary = ext_binary()</v>
+ <v>Binary = <seealso marker="#type-ext_binary">ext_binary()</seealso></v>
</type>
<desc>
<p>Returns an Erlang term which is the result of decoding
@@ -354,11 +401,11 @@ iolist() = [char() | binary() | iolist()]
</desc>
</func>
<func>
- <name>erlang:binary_to_term(Binary, Opts) -> term()</name>
+ <name>binary_to_term(Binary, Opts) -> term()</name>
<fsummary>Decode an Erlang external term format binary</fsummary>
<type>
<v>Opts = [safe]</v>
- <v>Binary = ext_binary()</v>
+ <v>Binary = <seealso marker="#type-ext_binary">ext_binary()</seealso></v>
</type>
<desc>
<p>As <c>binary_to_term/1</c>, but takes options that affect decoding
@@ -389,7 +436,7 @@ iolist() = [char() | binary() | iolist()]
</desc>
</func>
<func>
- <name>bit_size(Bitstring) -> int()</name>
+ <name>bit_size(Bitstring) -> integer() >= 0</name>
<fsummary>Return the size of a bitstring</fsummary>
<type>
<v>Bitstring = bitstring()</v>
@@ -408,7 +455,7 @@ iolist() = [char() | binary() | iolist()]
<name>erlang:bump_reductions(Reductions) -> void()</name>
<fsummary>Increment the reduction counter</fsummary>
<type>
- <v>Reductions = int()</v>
+ <v>Reductions = integer() >= 0</v>
</type>
<desc>
<p>This implementation-dependent function increments
@@ -425,7 +472,7 @@ iolist() = [char() | binary() | iolist()]
</desc>
</func>
<func>
- <name>byte_size(Bitstring) -> int()</name>
+ <name>byte_size(Bitstring) -> integer() >= 0</name>
<fsummary>Return the size of a bitstring (or binary)</fsummary>
<type>
<v>Bitstring = bitstring()</v>
@@ -446,8 +493,8 @@ iolist() = [char() | binary() | iolist()]
<name>erlang:cancel_timer(TimerRef) -> Time | false</name>
<fsummary>Cancel a timer</fsummary>
<type>
- <v>TimerRef = ref()</v>
- <v>Time = int()</v>
+ <v>TimerRef = reference()</v>
+ <v>Time = integer() >= 0</v>
</type>
<desc>
<p>Cancels a timer, where <c>TimerRef</c> was returned by
@@ -471,7 +518,19 @@ iolist() = [char() | binary() | iolist()]
</func>
<func>
- <name>check_process_code(Pid, Module) -> bool()</name>
+ <name>check_old_code(Module) -> boolean()</name>
+ <fsummary>Check if a module has old code</fsummary>
+ <type>
+ <v>Module = atom()</v>
+ </type>
+ <desc>
+ <p>Returns <c>true</c> if the <c>Module</c> has old code,
+ and <c>false</c> otherwise.</p>
+ <p>See also <seealso marker="kernel:code">code(3)</seealso>.</p>
+ </desc>
+ </func>
+ <func>
+ <name>check_process_code(Pid, Module) -> boolean()</name>
<fsummary>Check if a process is executing old code for a module</fsummary>
<type>
<v>Pid = pid()</v>
@@ -491,7 +550,7 @@ false</pre>
</desc>
</func>
<func>
- <name>concat_binary(ListOfBinaries)</name>
+ <name name="concat_binary" arity="1"/>
<fsummary>Concatenate a list of binaries (deprecated)</fsummary>
<desc>
<p>Do not use; use
@@ -500,7 +559,7 @@ false</pre>
</desc>
</func>
<func>
- <name>crc32(Data) -> int()</name>
+ <name>erlang:crc32(Data) -> integer() >= 0</name>
<fsummary>Compute crc32 (IEEE 802.3) checksum</fsummary>
<type>
<v>Data = iodata()</v>
@@ -510,10 +569,10 @@ false</pre>
</desc>
</func>
<func>
- <name>crc32(OldCrc, Data) -> int()</name>
+ <name>erlang:crc32(OldCrc, Data) -> integer() >= 0</name>
<fsummary>Compute crc32 (IEEE 802.3) checksum</fsummary>
<type>
- <v>OldCrc = int()</v>
+ <v>OldCrc = integer() >= 0</v>
<v>Data = iodata()</v>
</type>
<desc>
@@ -522,21 +581,21 @@ false</pre>
<c>Data</c>.</p>
<p>The following code:</p>
<code>
- X = crc32(Data1),
- Y = crc32(X,Data2).
+ X = erlang:crc32(Data1),
+ Y = erlang:crc32(X,Data2).
</code>
<p>- would assign the same value to <c>Y</c> as this would:</p>
<code>
- Y = crc32([Data1,Data2]).
+ Y = erlang:crc32([Data1,Data2]).
</code>
</desc>
</func>
<func>
- <name>crc32_combine(FirstCrc, SecondCrc, SecondSize) -> int()</name>
+ <name>erlang:crc32_combine(FirstCrc, SecondCrc, SecondSize) -> integer() >= 0</name>
<fsummary>Combine two crc32 (IEEE 802.3) checksums</fsummary>
<type>
- <v>FirstCrc = SecondCrc = int()</v>
- <v>SecondSize = int()</v>
+ <v>FirstCrc = SecondCrc = integer() >= 0</v>
+ <v>SecondSize = integer() >= 0</v>
</type>
<desc>
<p>Combines two previously computed crc32 checksums.
@@ -544,22 +603,22 @@ false</pre>
the second checksum to be known.</p>
<p>The following code:</p>
<code>
- Y = crc32(Data1),
- Z = crc32(Y,Data2).
+ Y = erlang:crc32(Data1),
+ Z = erlang:crc32(Y,Data2).
</code>
<p>- would assign the same value to <c>Z</c> as this would:</p>
<code>
- X = crc32(Data1),
- Y = crc32(Data2),
- Z = crc32_combine(X,Y,iolist_size(Data2)).
+ X = erlang:crc32(Data1),
+ Y = erlang:crc32(Data2),
+ Z = erlang:crc32_combine(X,Y,iolist_size(Data2)).
</code>
</desc>
</func>
<func>
- <name>date() -> {Year, Month, Day}</name>
+ <name>date() -> Date</name>
<fsummary>Current date</fsummary>
<type>
- <v>Year = Month = Day = int()</v>
+ <v>Date = <seealso marker="calendar#type-date">calendar:date()</seealso></v>
</type>
<desc>
<p>Returns the current date as <c>{Year, Month, Day}</c>.</p>
@@ -571,27 +630,27 @@ false</pre>
</desc>
</func>
<func>
- <name>decode_packet(Type,Bin,Options) -> {ok,Packet,Rest} | {more,Length} | {error,Reason}</name>
+ <name>erlang:decode_packet(Type,Bin,Options) -> {ok,Packet,Rest} | {more,Length} | {error,Reason}</name>
<fsummary>Extracts a protocol packet from a binary</fsummary>
<type>
<v>Bin = binary()</v>
<v>Options = [Opt]</v>
<v>Packet = binary() | HttpPacket</v>
<v>Rest = binary()</v>
- <v>Length = int() | undefined</v>
+ <v>Length = integer() > 0 | undefined</v>
<v>Reason = term()</v>
<v>&nbsp;Type, Opt -- see below</v>
<v></v>
<v>HttpPacket = HttpRequest | HttpResponse | HttpHeader | http_eoh | HttpError</v>
<v>HttpRequest = {http_request, HttpMethod, HttpUri, HttpVersion}</v>
<v>HttpResponse = {http_response, HttpVersion, integer(), HttpString}</v>
- <v>HttpHeader = {http_header, int(), HttpField, Reserved=term(), Value=HttpString}</v>
+ <v>HttpHeader = {http_header, integer(), HttpField, Reserved=term(), Value=HttpString}</v>
<v>HttpError = {http_error, HttpString}</v>
<v>HttpMethod = HttpMethodAtom | HttpString</v>
<v>HttpMethodAtom = 'OPTIONS' | 'GET' | 'HEAD' | 'POST' | 'PUT' | 'DELETE' | 'TRACE'</v>
- <v>HttpUri = '*' | {absoluteURI, http|https, Host=HttpString, Port=int()|undefined, Path=HttpString} |
+ <v>HttpUri = '*' | {absoluteURI, http|https, Host=HttpString, Port=integer()|undefined, Path=HttpString} |
{scheme, Scheme=HttpString, HttpString} | {abs_path, HttpString} | HttpString</v>
- <v>HttpVersion = {Major=int(), Minor=int()}</v>
+ <v>HttpVersion = {Major=integer(), Minor=integer()}</v>
<v>HttpString = string() | binary()</v>
<v>HttpField = HttpFieldAtom | HttpString</v>
<v>HttpFieldAtom = 'Cache-Control' | 'Connection' | 'Date' | 'Pragma' | 'Transfer-Encoding' | 'Upgrade' | 'Via' | 'Accept' | 'Accept-Charset' | 'Accept-Encoding' | 'Accept-Language' | 'Authorization' | 'From' | 'Host' | 'If-Modified-Since' | 'If-Match' | 'If-None-Match' | 'If-Range' | 'If-Unmodified-Since' | 'Max-Forwards' | 'Proxy-Authorization' | 'Range' | 'Referer' | 'User-Agent' | 'Age' | 'Location' | 'Proxy-Authenticate' | 'Public' | 'Retry-After' | 'Server' | 'Vary' | 'Warning' | 'Www-Authenticate' | 'Allow' | 'Content-Base' | 'Content-Encoding' | 'Content-Language' | 'Content-Length' | 'Content-Location' | 'Content-Md5' | 'Content-Range' | 'Content-Type' | 'Etag' | 'Expires' | 'Last-Modified' | 'Accept-Ranges' | 'Set-Cookie' | 'Set-Cookie2' | 'X-Forwarded-For' | 'Cookie' | 'Keep-Alive' | 'Proxy-Connection'</v>
@@ -666,14 +725,14 @@ false</pre>
</taglist>
<p>The following options are available:</p>
<taglist>
- <tag><c>{packet_size, int()}</c></tag>
+ <tag><c>{packet_size, integer()}</c></tag>
<item><p>Sets the max allowed size of the packet body. If
the packet header indicates that the length of the
packet is longer than the max allowed length, the packet
is considered invalid. Default is 0 which means no
size limit.</p>
</item>
- <tag><c>{line_length, int()}</c></tag>
+ <tag><c>{line_length, integer()}</c></tag>
<item><p>Applies only to line oriented protocols
(<c>line</c>, <c>http</c>). Lines longer than this
will be truncated.</p>
@@ -707,18 +766,18 @@ false</pre>
</desc>
</func>
<func>
- <name>erlang:demonitor(MonitorRef) -> true</name>
+ <name>demonitor(MonitorRef) -> true</name>
<fsummary>Stop monitoring</fsummary>
<type>
- <v>MonitorRef = ref()</v>
+ <v>MonitorRef = reference()</v>
</type>
<desc>
<p>If <c>MonitorRef</c> is a reference which the calling process
obtained by calling
- <seealso marker="#monitor/2">erlang:monitor/2</seealso>,
+ <seealso marker="#monitor/2">monitor/2</seealso>,
this monitoring is turned off. If the monitoring is already
turned off, nothing happens.</p>
- <p>Once <c>erlang:demonitor(MonitorRef)</c> has returned it is
+ <p>Once <c>demonitor(MonitorRef)</c> has returned it is
guaranteed that no <c>{'DOWN', MonitorRef, _, _, _}</c> message
due to the monitor will be placed in the callers message queue
in the future. A <c>{'DOWN', MonitorRef, _, _, _}</c> message
@@ -726,10 +785,10 @@ false</pre>
the call, though. Therefore, in most cases, it is advisable
to remove such a <c>'DOWN'</c> message from the message queue
after monitoring has been stopped.
- <seealso marker="#demonitor/2">erlang:demonitor(MonitorRef, [flush])</seealso> can be used instead of
- <c>erlang:demonitor(MonitorRef)</c> if this cleanup is wanted.</p>
+ <seealso marker="#demonitor/2">demonitor(MonitorRef, [flush])</seealso> can be used instead of
+ <c>demonitor(MonitorRef)</c> if this cleanup is wanted.</p>
<note>
- <p>Prior to OTP release R11B (erts version 5.5) <c>erlang:demonitor/1</c>
+ <p>Prior to OTP release R11B (erts version 5.5) <c>demonitor/1</c>
behaved completely asynchronous, i.e., the monitor was active
until the "demonitor signal" reached the monitored entity. This
had one undesirable effect, though. You could never know when
@@ -747,10 +806,10 @@ false</pre>
</desc>
</func>
<func>
- <name>erlang:demonitor(MonitorRef, OptionList) -> true|false</name>
+ <name>demonitor(MonitorRef, OptionList) -> boolean()</name>
<fsummary>Stop monitoring</fsummary>
<type>
- <v>MonitorRef = ref()</v>
+ <v>MonitorRef = reference()</v>
<v>OptionList = [Option]</v>
<v>Option = flush</v>
<v>Option = info</v>
@@ -759,8 +818,8 @@ false</pre>
<p>The returned value is <c>true</c> unless <c>info</c> is part
of <c>OptionList</c>.
</p>
- <p><c>erlang:demonitor(MonitorRef, [])</c> is equivalent to
- <seealso marker="#demonitor/1">erlang:demonitor(MonitorRef)</seealso>.</p>
+ <p><c>demonitor(MonitorRef, [])</c> is equivalent to
+ <seealso marker="#demonitor/1">demonitor(MonitorRef)</seealso>.</p>
<p>Currently the following <c>Option</c>s are valid:</p>
<taglist>
<tag><c>flush</c></tag>
@@ -768,11 +827,11 @@ false</pre>
<p>Remove (one) <c>{_, MonitorRef, _, _, _}</c> message,
if there is one, from the callers message queue after
monitoring has been stopped.</p>
- <p>Calling <c>erlang:demonitor(MonitorRef, [flush])</c>
+ <p>Calling <c>demonitor(MonitorRef, [flush])</c>
is equivalent to the following, but more efficient:</p>
<code type="none">
- erlang:demonitor(MonitorRef),
+ demonitor(MonitorRef),
receive
{_, MonitorRef, _, _, _} ->
true
@@ -810,18 +869,15 @@ false</pre>
</note>
<p>Failure: <c>badarg</c> if <c>OptionList</c> is not a list, or
if <c>Option</c> is not a valid option, or the same failure as for
- <seealso marker="#demonitor/1">erlang:demonitor/1</seealso></p>
+ <seealso marker="#demonitor/1">demonitor/1</seealso></p>
</desc>
</func>
<func>
- <name>disconnect_node(Node) -> bool() | ignored</name>
+ <name name="disconnect_node" arity="1"/>
<fsummary>Force the disconnection of a node</fsummary>
- <type>
- <v>Node = atom()</v>
- </type>
<desc>
<p>Forces the disconnection of a node. This will appear to
- the node <c>Node</c> as if the local node has crashed. This
+ the node <c><anno>Node</anno></c> as if the local node has crashed. This
BIF is mainly used in the Erlang network authentication
protocols. Returns <c>true</c> if disconnection succeeds,
otherwise <c>false</c>. If the local node is not alive,
@@ -891,7 +947,7 @@ b</pre>
</desc>
</func>
<func>
- <name>erlang:error(Reason)</name>
+ <name>error(Reason)</name>
<fsummary>Stop execution with a given reason</fsummary>
<type>
<v>Reason = term()</v>
@@ -904,7 +960,7 @@ b</pre>
function first). Since evaluating this function causes
the process to terminate, it has no return value.</p>
<pre>
-> <input>catch erlang:error(foobar).</input>
+> <input>catch error(foobar).</input>
{'EXIT',{foobar,[{erl_eval,do_apply,5},
{erl_eval,expr,5},
{shell,exprs,6},
@@ -913,7 +969,7 @@ b</pre>
</desc>
</func>
<func>
- <name>erlang:error(Reason, Args)</name>
+ <name>error(Reason, Args)</name>
<fsummary>Stop execution with a given reason</fsummary>
<type>
<v>Reason = term()</v>
@@ -979,6 +1035,56 @@ b</pre>
</desc>
</func>
<func>
+ <name>erlang:external_size(Term) -> integer() >= 0</name>
+ <fsummary>Calculate the maximum size for a term encoded in the Erlang
+ external term format</fsummary>
+ <type>
+ <v>Term = term()</v>
+ </type>
+ <desc>
+ <p>Calculates, without doing the encoding, the maximum byte size for
+ a term encoded in the Erlang external term format. The following
+ condition applies always:</p>
+ <p>
+ <pre>
+> <input>Size1 = byte_size(term_to_binary(Term)),</input>
+> <input>Size2 = erlang:external_size(Term),</input>
+> <input>true = Size1 =&lt; Size2.</input>
+true
+ </pre>
+ </p>
+ <p>This is equivalent to a call to: <code>erlang:external_size(Term, [])
+ </code></p>
+ </desc>
+ </func>
+ <func>
+ <name>erlang:external_size(Term, [Option]) -> integer() >= 0</name>
+ <fsummary>Calculate the maximum size for a term encoded in the Erlang
+ external term format</fsummary>
+ <type>
+ <v>Term = term()</v>
+ <v>Option = {minor_version, Version}</v>
+ </type>
+ <desc>
+ <p>Calculates, without doing the encoding, the maximum byte size for
+ a term encoded in the Erlang external term format. The following
+ condition applies always:</p>
+ <p>
+ <pre>
+> <input>Size1 = byte_size(term_to_binary(Term, Options)),</input>
+> <input>Size2 = erlang:external_size(Term, Options),</input>
+> <input>true = Size1 =&lt; Size2.</input>
+true
+ </pre>
+ </p>
+ <p>The option <c>{minor_version, Version}</c> specifies how floats
+ are encoded. See
+ <seealso marker="#term_to_binary/2">term_to_binary/2</seealso> for
+ a more detailed description.
+ </p>
+ </desc>
+ </func>
+ <func>
<name>float(Number) -> float()</name>
<fsummary>Convert a number to a float</fsummary>
<type>
@@ -1016,15 +1122,11 @@ b</pre>
</desc>
</func>
<func>
- <name>erlang:fun_info(Fun) -> [{Item, Info}]</name>
+ <name name="fun_info" arity="1"/>
<fsummary>Information about a fun</fsummary>
- <type>
- <v>Fun = fun()</v>
- <v>Item, Info -- see below</v>
- </type>
<desc>
<p>Returns a list containing information about the fun
- <c>Fun</c>. Each element of the list is a tuple. The order of
+ <c><anno>Fun</anno></c>. Each element of the list is a tuple. The order of
the tuples is not defined, and more tuples may be added in a
future release.</p>
<warning>
@@ -1123,7 +1225,7 @@ b</pre>
<p>Returns information about <c>Fun</c> as specified by
<c>Item</c>, in the form <c>{Item,Info}</c>.</p>
<p>For any fun, <c>Item</c> can be any of the atoms
- <c>module</c>, <c>name</c>, <c>arity</c>, or <c>env</c>.</p>
+ <c>module</c>, <c>name</c>, <c>arity</c>, <c>env</c>, or <c>type</c>.</p>
<p>For a local fun, <c>Item</c> can also be any of the atoms
<c>index</c>, <c>new_index</c>, <c>new_uniq</c>,
<c>uniq</c>, and <c>pid</c>. For an external fun, the value
@@ -1144,11 +1246,11 @@ b</pre>
</desc>
</func>
<func>
- <name>erlang:function_exported(Module, Function, Arity) -> bool()</name>
+ <name>erlang:function_exported(Module, Function, Arity) -> boolean()</name>
<fsummary>Check if a function is exported and loaded</fsummary>
<type>
<v>Module = Function = atom()</v>
- <v>Arity = int()</v>
+ <v>Arity = arity()</v>
</type>
<desc>
<p>Returns <c>true</c> if the module <c>Module</c> is loaded
@@ -1176,7 +1278,7 @@ b</pre>
</desc>
</func>
<func>
- <name>garbage_collect(Pid) -> bool()</name>
+ <name>garbage_collect(Pid) -> boolean()</name>
<fsummary>Force an immediate garbage collection of a process</fsummary>
<type>
<v>Pid = pid()</v>
@@ -1223,11 +1325,8 @@ b</pre>
</desc>
</func>
<func>
- <name>erlang:get_cookie() -> Cookie | nocookie</name>
+ <name name="get_cookie" arity="0"/>
<fsummary>Get the magic cookie of the local node</fsummary>
- <type>
- <v>Cookie = atom()</v>
- </type>
<desc>
<p>Returns the magic cookie of the local node, if the node is
alive; otherwise the atom <c>nocookie</c>.</p>
@@ -1258,7 +1357,7 @@ b</pre>
<fsummary>Get the call stack back-trace of the last exception</fsummary>
<type>
<v>Module = Function = atom()</v>
- <v>Arity = int()</v>
+ <v>Arity = arity()</v>
<v>Args = [term()]</v>
</type>
<desc>
@@ -1326,7 +1425,7 @@ os_prompt%</pre>
<name>halt(Status)</name>
<fsummary>Halt the Erlang runtime system</fsummary>
<type>
- <v>Status = int()>=0 | string()</v>
+ <v>Status = integer() >= 0 | string()</v>
</type>
<desc>
<p><c>Status</c> must be a non-negative integer, or a string.
@@ -1419,7 +1518,7 @@ os_prompt%</pre>
<name>integer_to_list(Integer) -> string()</name>
<fsummary>Text representation of an integer</fsummary>
<type>
- <v>Integer = int()</v>
+ <v>Integer = integer()</v>
</type>
<desc>
<p>Returns a string which corresponds to the text
@@ -1430,17 +1529,13 @@ os_prompt%</pre>
</desc>
</func>
<func>
- <name>erlang:integer_to_list(Integer, Base) -> string()</name>
+ <name name="integer_to_list" arity="2"/>
<fsummary>Text representation of an integer</fsummary>
- <type>
- <v>Integer = int()</v>
- <v>Base = 2..36</v>
- </type>
<desc>
<p>Returns a string which corresponds to the text
- representation of <c>Integer</c> in base <c>Base</c>.</p>
+ representation of <c><anno>Integer</anno></c> in base <c><anno>Base</anno></c>.</p>
<pre>
-> <input>erlang:integer_to_list(1023, 16).</input>
+> <input>integer_to_list(1023, 16).</input>
"3FF"</pre>
</desc>
</func>
@@ -1465,7 +1560,7 @@ os_prompt%</pre>
</desc>
</func>
<func>
- <name>iolist_size(Item) -> int()</name>
+ <name>iolist_size(Item) -> integer() >= 0</name>
<fsummary>Size of an iolist</fsummary>
<type>
<v>Item = iolist() | binary()</v>
@@ -1480,7 +1575,7 @@ os_prompt%</pre>
</desc>
</func>
<func>
- <name>is_alive() -> bool()</name>
+ <name>is_alive() -> boolean()</name>
<fsummary>Check whether the local node is alive</fsummary>
<desc>
<p>Returns <c>true</c> if the local node is alive; that is, if
@@ -1489,7 +1584,7 @@ os_prompt%</pre>
</desc>
</func>
<func>
- <name>is_atom(Term) -> bool()</name>
+ <name>is_atom(Term) -> boolean()</name>
<fsummary>Check whether a term is an atom</fsummary>
<type>
<v>Term = term()</v>
@@ -1501,7 +1596,7 @@ os_prompt%</pre>
</desc>
</func>
<func>
- <name>is_binary(Term) -> bool()</name>
+ <name>is_binary(Term) -> boolean()</name>
<fsummary>Check whether a term is a binary</fsummary>
<type>
<v>Term = term()</v>
@@ -1516,7 +1611,7 @@ os_prompt%</pre>
</desc>
</func>
<func>
- <name>is_bitstring(Term) -> bool()</name>
+ <name>is_bitstring(Term) -> boolean()</name>
<fsummary>Check whether a term is a bitstring</fsummary>
<type>
<v>Term = term()</v>
@@ -1529,7 +1624,7 @@ os_prompt%</pre>
</desc>
</func>
<func>
- <name>is_boolean(Term) -> bool()</name>
+ <name>is_boolean(Term) -> boolean()</name>
<fsummary>Check whether a term is a boolean</fsummary>
<type>
<v>Term = term()</v>
@@ -1542,11 +1637,11 @@ os_prompt%</pre>
</desc>
</func>
<func>
- <name>erlang:is_builtin(Module, Function, Arity) -> bool()</name>
+ <name>erlang:is_builtin(Module, Function, Arity) -> boolean()</name>
<fsummary>Check if a function is a BIF implemented in C</fsummary>
<type>
<v>Module = Function = atom()</v>
- <v>Arity = int()</v>
+ <v>Arity = arity()</v>
</type>
<desc>
<p>Returns <c>true</c> if <c>Module:Function/Arity</c> is
@@ -1555,7 +1650,7 @@ os_prompt%</pre>
</desc>
</func>
<func>
- <name>is_float(Term) -> bool()</name>
+ <name>is_float(Term) -> boolean()</name>
<fsummary>Check whether a term is a float</fsummary>
<type>
<v>Term = term()</v>
@@ -1567,7 +1662,7 @@ os_prompt%</pre>
</desc>
</func>
<func>
- <name>is_function(Term) -> bool()</name>
+ <name>is_function(Term) -> boolean()</name>
<fsummary>Check whether a term is a fun</fsummary>
<type>
<v>Term = term()</v>
@@ -1579,11 +1674,11 @@ os_prompt%</pre>
</desc>
</func>
<func>
- <name>is_function(Term, Arity) -> bool()</name>
+ <name>is_function(Term, Arity) -> boolean()</name>
<fsummary>Check whether a term is a fun with a given arity</fsummary>
<type>
<v>Term = term()</v>
- <v>Arity = int()</v>
+ <v>Arity = arity()</v>
</type>
<desc>
<p>Returns <c>true</c> if <c>Term</c> is a fun that can be
@@ -1600,7 +1695,7 @@ os_prompt%</pre>
</desc>
</func>
<func>
- <name>is_integer(Term) -> bool()</name>
+ <name>is_integer(Term) -> boolean()</name>
<fsummary>Check whether a term is an integer</fsummary>
<type>
<v>Term = term()</v>
@@ -1612,7 +1707,7 @@ os_prompt%</pre>
</desc>
</func>
<func>
- <name>is_list(Term) -> bool()</name>
+ <name>is_list(Term) -> boolean()</name>
<fsummary>Check whether a term is a list</fsummary>
<type>
<v>Term = term()</v>
@@ -1624,7 +1719,7 @@ os_prompt%</pre>
</desc>
</func>
<func>
- <name>is_number(Term) -> bool()</name>
+ <name>is_number(Term) -> boolean()</name>
<fsummary>Check whether a term is a number</fsummary>
<type>
<v>Term = term()</v>
@@ -1636,7 +1731,7 @@ os_prompt%</pre>
</desc>
</func>
<func>
- <name>is_pid(Term) -> bool()</name>
+ <name>is_pid(Term) -> boolean()</name>
<fsummary>Check whether a term is a pid</fsummary>
<type>
<v>Term = term()</v>
@@ -1648,7 +1743,7 @@ os_prompt%</pre>
</desc>
</func>
<func>
- <name>is_port(Term) -> bool()</name>
+ <name>is_port(Term) -> boolean()</name>
<fsummary>Check whether a term is a port</fsummary>
<type>
<v>Term = term()</v>
@@ -1660,7 +1755,7 @@ os_prompt%</pre>
</desc>
</func>
<func>
- <name>is_process_alive(Pid) -> bool()</name>
+ <name>is_process_alive(Pid) -> boolean()</name>
<fsummary>Check whether a process is alive</fsummary>
<type>
<v>Pid = pid()</v>
@@ -1675,7 +1770,7 @@ os_prompt%</pre>
</desc>
</func>
<func>
- <name>is_record(Term, RecordTag) -> bool()</name>
+ <name>is_record(Term, RecordTag) -> boolean()</name>
<fsummary>Check whether a term appears to be a record</fsummary>
<type>
<v>Term = term()</v>
@@ -1698,12 +1793,12 @@ os_prompt%</pre>
</desc>
</func>
<func>
- <name>is_record(Term, RecordTag, Size) -> bool()</name>
+ <name>is_record(Term, RecordTag, Size) -> boolean()</name>
<fsummary>Check whether a term appears to be a record</fsummary>
<type>
<v>Term = term()</v>
<v>RecordTag = atom()</v>
- <v>Size = int()</v>
+ <v>Size = integer()</v>
</type>
<desc>
<p><c>RecordTag</c> must be an atom. Returns <c>true</c> if
@@ -1718,7 +1813,7 @@ os_prompt%</pre>
</desc>
</func>
<func>
- <name>is_reference(Term) -> bool()</name>
+ <name>is_reference(Term) -> boolean()</name>
<fsummary>Check whether a term is a reference</fsummary>
<type>
<v>Term = term()</v>
@@ -1730,7 +1825,7 @@ os_prompt%</pre>
</desc>
</func>
<func>
- <name>is_tuple(Term) -> bool()</name>
+ <name>is_tuple(Term) -> boolean()</name>
<fsummary>Check whether a term is a tuple</fsummary>
<type>
<v>Term = term()</v>
@@ -1742,7 +1837,7 @@ os_prompt%</pre>
</desc>
</func>
<func>
- <name>length(List) -> int()</name>
+ <name>length(List) -> integer() >= 0</name>
<fsummary>Length of a list</fsummary>
<type>
<v>List = [term()]</v>
@@ -1863,7 +1958,7 @@ os_prompt%</pre>
</desc>
</func>
<func>
- <name>list_to_integer(String) -> int()</name>
+ <name>list_to_integer(String) -> integer()</name>
<fsummary>Convert from text representation to an integer</fsummary>
<type>
<v>String = string()</v>
@@ -1879,19 +1974,15 @@ os_prompt%</pre>
</desc>
</func>
<func>
- <name>erlang:list_to_integer(String, Base) -> int()</name>
+ <name name="list_to_integer" arity="2"/>
<fsummary>Convert from text representation to an integer</fsummary>
- <type>
- <v>String = string()</v>
- <v>Base = 2..36</v>
- </type>
<desc>
<p>Returns an integer whose text representation in base
- <c>Base</c> is <c>String</c>.</p>
+ <c><anno>Base</anno></c> is <c><anno>String</anno></c>.</p>
<pre>
-> <input>erlang:list_to_integer("3FF", 16).</input>
+> <input>list_to_integer("3FF", 16).</input>
1023</pre>
- <p>Failure: <c>badarg</c> if <c>String</c> contains a bad
+ <p>Failure: <c>badarg</c> if <c><anno>String</anno></c> contains a bad
representation of an integer.</p>
</desc>
</func>
@@ -1981,16 +2072,18 @@ os_prompt%</pre>
<v>Text = string()</v>
</type>
<desc>
- <warning>
- <p>This BIF is still an experimental feature. The interface
- may be changed in any way in future releases.</p><p>In
- R13B03 the return value on failure was
+ <note>
+ <p>In releases older than OTP R14B, NIFs were an
+ experimental feature. Versions of OTP older than R14B might
+ have different and possibly incompatible NIF semantics and
+ interfaces. For example, in R13B03 the return value on
+ failure was
<c>{error,Reason,Text}</c>.</p>
- </warning>
+ </note>
<p>Loads and links a dynamic library containing native
implemented functions (NIFs) for a module. <c>Path</c> is a
file path to the sharable object/dynamic library file minus
- the OS-dependant file extension (.so for Unix and .ddl for
+ the OS-dependent file extension (.so for Unix and .dll for
Windows). See <seealso marker="erl_nif">erl_nif</seealso>
on how to implement a NIF library.</p>
<p><c>LoadInfo</c> can be any term. It will be passed on to
@@ -2040,12 +2133,10 @@ os_prompt%</pre>
</desc>
</func>
<func>
- <name>erlang:localtime() -> {Date, Time}</name>
+ <name>erlang:localtime() -> DateTime</name>
<fsummary>Current local date and time</fsummary>
<type>
- <v>Date = {Year, Month, Day}</v>
- <v>Time = {Hour, Minute, Second}</v>
- <v>&nbsp;Year = Month = Day = Hour = Minute = Second = int()</v>
+ <v>DateTime = <seealso marker="calendar#type-datetime">calendar:datetime()</seealso></v>
</type>
<desc>
<p>Returns the current local date and time
@@ -2058,17 +2149,12 @@ os_prompt%</pre>
</desc>
</func>
<func>
- <name>erlang:localtime_to_universaltime({Date1, Time1}) -> {Date2, Time2}</name>
+ <name name="localtime_to_universaltime" arity="1"/>
<fsummary>Convert from local to Universal Time Coordinated (UTC) date and time</fsummary>
- <type>
- <v>Date1 = Date2 = {Year, Month, Day}</v>
- <v>Time1 = Time2 = {Hour, Minute, Second}</v>
- <v>&nbsp;Year = Month = Day = Hour = Minute = Second = int()</v>
- </type>
<desc>
<p>Converts local date and time to Universal Time Coordinated
(UTC), if this is supported by the underlying OS. Otherwise,
- no conversion is done and <c>{Date1, Time1}</c> is returned.</p>
+ no conversion is done and <c>{<anno>Date1</anno>, <anno>Time1</anno>}</c> is returned.</p>
<pre>
> <input>erlang:localtime_to_universaltime({{1996,11,6},{14,45,17}}).</input>
{{1996,11,6},{13,45,17}}</pre>
@@ -2080,9 +2166,8 @@ os_prompt%</pre>
<name>erlang:localtime_to_universaltime({Date1, Time1}, IsDst) -> {Date2, Time2}</name>
<fsummary>Convert from local to Universal Time Coordinated (UTC) date and time</fsummary>
<type>
- <v>Date1 = Date2 = {Year, Month, Day}</v>
- <v>Time1 = Time2 = {Hour, Minute, Second}</v>
- <v>&nbsp;Year = Month = Day = Hour = Minute = Second = int()</v>
+ <v>Date1 = Date2 = <seealso marker="calendar#type-date">calendar:date()</seealso></v>
+ <v>Time1 = Time2 = <seealso marker="calendar#type-time">calendar:time()</seealso></v>
<v>IsDst = true | false | undefined</v>
</type>
<desc>
@@ -2107,7 +2192,7 @@ os_prompt%</pre>
</desc>
</func>
<func>
- <name>make_ref() -> ref()</name>
+ <name>make_ref() -> reference()</name>
<fsummary>Return an almost unique reference</fsummary>
<desc>
<p>Returns an almost unique reference.</p>
@@ -2122,7 +2207,7 @@ os_prompt%</pre>
<name>erlang:make_tuple(Arity, InitialValue) -> tuple()</name>
<fsummary>Create a new tuple of a given arity</fsummary>
<type>
- <v>Arity = int()</v>
+ <v>Arity = arity()</v>
<v>InitialValue = term()</v>
</type>
<desc>
@@ -2137,7 +2222,7 @@ os_prompt%</pre>
<name>erlang:make_tuple(Arity, Default, InitList) -> tuple()</name>
<fsummary>Create a new tuple with given arity and contents</fsummary>
<type>
- <v>Arity = int()</v>
+ <v>Arity = arity()</v>
<v>Default = term()</v>
<v>InitList = [{Position,term()}]</v>
<v>Position = integer()</v>
@@ -2156,14 +2241,11 @@ os_prompt%</pre>
</desc>
</func>
<func>
- <name>erlang:max(Term1, Term2) -> Maximum</name>
+ <name name="max" arity="2"/>
<fsummary>Return the largest of two term</fsummary>
- <type>
- <v>Term1 = Term2 = Maximum = term()</v>
- </type>
<desc>
- <p>Return the largest of <c>Term1</c> and <c>Term2</c>;
- if the terms compares equal, <c>Term1</c> will be returned.</p>
+ <p>Return the largest of <c><anno>Term1</anno></c> and <c><anno>Term2</anno></c>;
+ if the terms compare equal, <c><anno>Term1</anno></c> will be returned.</p>
</desc>
</func>
<func>
@@ -2301,6 +2383,14 @@ os_prompt%</pre>
<seealso marker="tools:instrument">instrument(3)</seealso>
and/or <seealso marker="erts:erl">erl(1)</seealso>.</p>
</item>
+ <tag><c>low</c></tag>
+ <item>
+ <p>Only on 64-bit halfword emulator.</p>
+ <p>The total amount of memory allocated in low memory areas
+ that are restricted to less than 4 Gb even though
+ the system may have more physical memory.</p>
+ <p>May be removed in future releases of halfword emulator.</p>
+ </item>
</taglist>
<note>
<p>The <c>system</c> value is not complete. Some allocated
@@ -2405,18 +2495,15 @@ os_prompt%</pre>
</desc>
</func>
<func>
- <name>erlang:min(Term1, Term2) -> Minimum</name>
+ <name name="min" arity="2"/>
<fsummary>Return the smallest of two term</fsummary>
- <type>
- <v>Term1 = Term2 = Minimum = term()</v>
- </type>
<desc>
- <p>Return the smallest of <c>Term1</c> and <c>Term2</c>;
- if the terms compare equal, <c>Term1</c> will be returned.</p>
+ <p>Return the smallest of <c><anno>Term1</anno></c> and <c><anno>Term2</anno></c>;
+ if the terms compare equal, <c><anno>Term1</anno></c> will be returned.</p>
</desc>
</func>
<func>
- <name>module_loaded(Module) -> bool()</name>
+ <name>module_loaded(Module) -> boolean()</name>
<fsummary>Check if a module is loaded</fsummary>
<type>
<v>Module = atom()</v>
@@ -2433,7 +2520,7 @@ os_prompt%</pre>
</desc>
</func>
<func>
- <name>erlang:monitor(Type, Item) -> MonitorRef</name>
+ <name>monitor(Type, Item) -> MonitorRef</name>
<fsummary>Start monitoring</fsummary>
<type>
<v>Type = process</v>
@@ -2469,7 +2556,7 @@ os_prompt%</pre>
<note>
<p>When a process is monitored by registered name, the process
that has the registered name at the time when
- <c>erlang:monitor/2</c> is called will be monitored.
+ <c>monitor/2</c> is called will be monitored.
The monitor will not be effected, if the registered name is
unregistered.</p>
</note>
@@ -2503,20 +2590,20 @@ os_prompt%</pre>
</item>
</taglist>
<note>
- <p>If/when <c>erlang:monitor/2</c> is extended (e.g. to
+ <p>If/when <c>monitor/2</c> is extended (e.g. to
handle other item types than <c>process</c>), other
possible values for <c>Object</c>, and <c>Info</c> in the
<c>'DOWN'</c> message will be introduced.</p>
</note>
<p>The monitoring is turned off either when the <c>'DOWN'</c>
message is sent, or when
- <seealso marker="#demonitor/1">erlang:demonitor/1</seealso>
+ <seealso marker="#demonitor/1">demonitor/1</seealso>
is called.</p>
<p>If an attempt is made to monitor a process on an older node
(where remote process monitoring is not implemented or one
where remote process monitoring by registered name is not
implemented), the call fails with <c>badarg</c>.</p>
- <p>Making several calls to <c>erlang:monitor/2</c> for the same
+ <p>Making several calls to <c>monitor/2</c> for the same
<c>Item</c> is not an error; it results in as many, completely
independent, monitorings.</p>
<note>
@@ -2539,7 +2626,7 @@ os_prompt%</pre>
<fsummary>Monitor the status of a node</fsummary>
<type>
<v>Node = node()</v>
- <v>Flag = bool()</v>
+ <v>Flag = boolean()</v>
</type>
<desc>
<p>Monitors the status of the node <c>Node</c>. If <c>Flag</c>
@@ -2565,7 +2652,7 @@ os_prompt%</pre>
<fsummary>Monitor the status of a node</fsummary>
<type>
<v>Node = node()</v>
- <v>Flag = bool()</v>
+ <v>Flag = boolean()</v>
<v>Options = [Option]</v>
<v>Option = allow_passive_connect</v>
</type>
@@ -2591,6 +2678,37 @@ os_prompt%</pre>
</desc>
</func>
<func>
+ <name>erlang:nif_error(Reason)</name>
+ <fsummary>Stop execution with a given reason</fsummary>
+ <type>
+ <v>Reason = term()</v>
+ </type>
+ <desc>
+ <p>Works exactly like
+ <seealso marker="#error/1">erlang:error/1</seealso>,
+ but Dialyzer thinks that this BIF will return an arbitrary term.
+ When used in a stub function for a NIF to generate an
+ exception when the NIF library is not loaded, Dialyzer
+ will not generate false warnings.</p>
+ </desc>
+ </func>
+ <func>
+ <name>erlang:nif_error(Reason, Args)</name>
+ <fsummary>Stop execution with a given reason</fsummary>
+ <type>
+ <v>Reason = term()</v>
+ <v>Args = [term()]</v>
+ </type>
+ <desc>
+ <p>Works exactly like
+ <seealso marker="#error/2">erlang:error/2</seealso>,
+ but Dialyzer thinks that this BIF will return an arbitrary term.
+ When used in a stub function for a NIF to generate an
+ exception when the NIF library is not loaded, Dialyzer
+ will not generate false warnings.</p>
+ </desc>
+ </func>
+ <func>
<name>node() -> Node</name>
<fsummary>Name of the local node</fsummary>
<type>
@@ -2606,7 +2724,7 @@ os_prompt%</pre>
<name>node(Arg) -> Node</name>
<fsummary>At which node is a pid, port or reference located</fsummary>
<type>
- <v>Arg = pid() | port() | ref()</v>
+ <v>Arg = pid() | port() | reference()</v>
<v>Node = node()</v>
</type>
<desc>
@@ -2617,11 +2735,8 @@ os_prompt%</pre>
</desc>
</func>
<func>
- <name>nodes() -> Nodes</name>
+ <name name="nodes" arity="0"/>
<fsummary>All visible nodes in the system</fsummary>
- <type>
- <v>Nodes = [node()]</v>
- </type>
<desc>
<p>Returns a list of all visible nodes in the system, excluding
the local node. Same as <c>nodes(visible)</c>.</p>
@@ -2671,11 +2786,12 @@ os_prompt%</pre>
</desc>
</func>
<func>
- <name>now() -> {MegaSecs, Secs, MicroSecs}</name>
- <fsummary>Elapsed time since 00:00 GMT</fsummary>
+ <name>now() -> timestamp()</name>
<type>
- <v>MegaSecs = Secs = MicroSecs = int()</v>
+ <v>timestamp() = {MegaSecs, Secs, MicroSecs}</v>
+ <v>MegaSecs = Secs = MicroSecs = integer() >= 0</v>
</type>
+ <fsummary>Elapsed time since 00:00 GMT</fsummary>
<desc>
<p>Returns the tuple <c>{MegaSecs, Secs, MicroSecs}</c> which is
the elapsed time since 00:00 GMT, January 1, 1970 (zero hour)
@@ -2683,8 +2799,10 @@ os_prompt%</pre>
Otherwise, some other point in time is chosen. It is also
guaranteed that subsequent calls to this BIF returns
continuously increasing values. Hence, the return value from
- <c>now()</c> can be used to generate unique time-stamps. It
- can only be used to check the local time of day if
+ <c>now()</c> can be used to generate unique time-stamps,
+ and if it is called in a tight loop on a fast machine
+ the time of the node can become skewed.</p>
+ <p>It can only be used to check the local time of day if
the time-zone info of the underlying operating system is
properly configured.</p>
</desc>
@@ -2693,14 +2811,17 @@ os_prompt%</pre>
<name>open_port(PortName, PortSettings) -> port()</name>
<fsummary>Open a port</fsummary>
<type>
- <v>PortName = {spawn, Command} | {spawn_driver, Command} | {spawn_executable, Command} | {fd, In, Out}</v>
+ <v>PortName = {spawn, Command} | {spawn_driver, Command} | {spawn_executable, FileName} | {fd, In, Out}</v>
<v>&nbsp;Command = string()</v>
- <v>&nbsp;In = Out = int()</v>
+ <v>&nbsp;FileName = [ FileNameChar ] | binary()</v>
+ <v>&nbsp;FileNameChar = integer() (1..255 or any Unicode codepoint, see description)</v>
+ <v>&nbsp;In = Out = integer()</v>
<v>PortSettings = [Opt]</v>
- <v>&nbsp;Opt = {packet, N} | stream | {line, L} | {cd, Dir} | {env, Env} | {args, [ string() ]} | {arg0, string()} | exit_status | use_stdio | nouse_stdio | stderr_to_stdout | in | out | binary | eof</v>
+ <v>&nbsp;Opt = {packet, N} | stream | {line, L} | {cd, Dir} | {env, Env} | {args, [ ArgString ]} | {arg0, ArgString} | exit_status | use_stdio | nouse_stdio | stderr_to_stdout | in | out | binary | eof</v>
<v>&nbsp;&nbsp;N = 1 | 2 | 4</v>
- <v>&nbsp;&nbsp;L = int()</v>
+ <v>&nbsp;&nbsp;L = integer()</v>
<v>&nbsp;&nbsp;Dir = string()</v>
+ <v>&nbsp;&nbsp;ArgString = [ FileNameChar ] | binary()</v>
<v>&nbsp;&nbsp;Env = [{Name, Val}]</v>
<v>&nbsp;&nbsp;&nbsp;Name = string()</v>
<v>&nbsp;&nbsp;&nbsp;Val = string() | false</v>
@@ -2749,7 +2870,7 @@ os_prompt%</pre>
<item>
<p>Works like <c>{spawn, Command}</c>, but only runs
- external executables. The <c>Command</c> in it's whole
+ external executables. The <c>Command</c> in its whole
is used as the name of the executable, including any
spaces. If arguments are to be passed, the
<c>args</c> and <c>arg0</c> <c>PortSettings</c> can be used.</p>
@@ -2763,7 +2884,26 @@ os_prompt%</pre>
executed, the appropriate command interpreter will
implicitly be invoked, but there will still be no
command argument expansion or implicit PATH search.</p>
-
+
+ <p>The name of the executable as well as the arguments
+ given in <c>args</c> and <c>arg0</c> is subject to
+ Unicode file name translation if the system is running
+ in Unicode file name mode. To avoid
+ translation or force i.e. UTF-8, supply the executable
+ and/or arguments as a binary in the correct
+ encoding. See the <seealso
+ marker="kernel:file">file</seealso> module, the
+ <seealso marker="kernel:file#native_name_encoding/0">
+ file:native_name_encoding/0</seealso> function and the
+ <seealso marker="stdlib:unicode_usage">stdlib users guide
+ </seealso> for details.</p>
+
+ <note><p>The characters in the name (if given as a list)
+ can only be &gt; 255 if the Erlang VM is started in
+ Unicode file name translation mode, otherwise the name
+ of the executable is limited to the ISO-latin-1
+ character set.</p></note>
+
<p>If the <c>Command</c> cannot be run, an error
exception, with the posix error code as the reason, is
raised. The error reason may differ between operating
@@ -2866,6 +3006,21 @@ os_prompt%</pre>
should not be given in this list. The proper executable name will
automatically be used as argv[0] where applicable.</p>
+ <p>When the Erlang VM is running in Unicode file name
+ mode, the arguments can contain any Unicode characters and
+ will be translated into whatever is appropriate on the
+ underlying OS, which means UTF-8 for all platforms except
+ Windows, which has other (more transparent) ways of
+ dealing with Unicode arguments to programs. To avoid
+ Unicode translation of arguments, they can be supplied as
+ binaries in whatever encoding is deemed appropriate.</p>
+
+ <note><p>The characters in the arguments (if given as a
+ list of characters) can only be &gt; 255 if the Erlang
+ VM is started in Unicode file name mode,
+ otherwise the arguments are limited to the
+ ISO-latin-1 character set.</p></note>
+
<p>If one, for any reason, wants to explicitly set the
program name in the argument vector, the <c>arg0</c>
option can be used.</p>
@@ -2881,6 +3036,9 @@ os_prompt%</pre>
responds to this is highly system dependent and no specific
effect is guaranteed.</p>
+ <p>The unicode file name translation rules of the
+ <c>args</c> option apply to this option as well.</p>
+
</item>
<tag><c>exit_status</c></tag>
@@ -2926,7 +3084,7 @@ os_prompt%</pre>
The standard input and standard output handles of the port program
will, if this option is supplied, be opened with the flag
FILE_FLAG_OVERLAPPED, so that the port program can (and has to) do
- overlapped I/O on it's standard handles. This is not normally
+ overlapped I/O on its standard handles. This is not normally
the case for simple port programs, but an option of value for the
experienced Windows programmer. <em>On all other platforms, this
option is silently discarded</em>.</p>
@@ -3147,7 +3305,7 @@ os_prompt%</pre>
</desc>
</func>
<func>
- <name>erlang:port_command(Port, Data, OptionList) -> true|false</name>
+ <name>port_command(Port, Data, OptionList) -> boolean()</name>
<fsummary>Send data to a port</fsummary>
<type>
<v>Port = port() | atom()</v>
@@ -3183,10 +3341,6 @@ os_prompt%</pre>
<note>
<p>More options may be added in the future.</p>
</note>
- <note>
- <p><c>erlang:port_command/3</c> is currently not auto imported, but
- it is planned to be auto imported in OTP R14.</p>
- </note>
<p>Failures:</p>
<taglist>
<tag><c>badarg</c></tag>
@@ -3267,7 +3421,7 @@ os_prompt%</pre>
<fsummary>Perform a synchronous control operation on a port</fsummary>
<type>
<v>Port = port() | atom()</v>
- <v>Operation = int()</v>
+ <v>Operation = integer()</v>
<v>Data = Res = iodata()</v>
</type>
<desc>
@@ -3291,7 +3445,7 @@ os_prompt%</pre>
<fsummary>Synchronous call to a port with term data</fsummary>
<type>
<v>Port = port() | atom()</v>
- <v>Operation = int()</v>
+ <v>Operation = integer()</v>
<v>Data = term()</v>
</type>
<desc>
@@ -3815,11 +3969,11 @@ os_prompt%</pre>
<tag><c>{monitored_by, Pids}</c></tag>
<item>
<p>A list of pids that are monitoring the process (with
- <c>erlang:monitor/2</c>).</p>
+ <c>monitor/2</c>).</p>
</item>
<tag><c>{monitors, Monitors}</c></tag>
<item>
- <p>A list of monitors (started by <c>erlang:monitor/2</c>)
+ <p>A list of monitors (started by <c>monitor/2</c>)
that are active for the process. For a local process
monitor or a remote process monitor by pid, the list item
is <c>{process, Pid}</c>, and for a remote process
@@ -3856,7 +4010,8 @@ os_prompt%</pre>
<tag><c>{status, Status}</c></tag>
<item>
<p><c>Status</c> is the status of the process. <c>Status</c>
- is <c>waiting</c> (waiting for a message), <c>running</c>,
+ is <c>exiting</c>, <c>garbage_collecting</c>,
+ <c>waiting</c> (for a message), <c>running</c>,
<c>runnable</c> (ready to run, but another process is
running), or <c>suspended</c> (suspended on a "busy" port
or by the <c>erlang:suspend_process/[1,2]</c> BIF).</p>
@@ -3976,7 +4131,7 @@ os_prompt%</pre>
<v>Reason = term()</v>
<v>Stacktrace = [{Module, Function, Arity | Args} | {Fun, Args}]</v>
<v>&nbsp;Module = Function = atom()</v>
- <v>&nbsp;Arity = int()</v>
+ <v>&nbsp;Arity = arity()</v>
<v>&nbsp;Args = [term()]</v>
<v>&nbsp;Fun = [fun()]</v>
</type>
@@ -4008,15 +4163,15 @@ os_prompt%</pre>
terminate, it has no return value - unless the arguments are
invalid, in which case the function <em>returns the error reason</em>, that is <c>badarg</c>. If you want to be
really sure not to return you can call
- <c>erlang:error(erlang:raise(Class, Reason, Stacktrace))</c>
+ <c>error(erlang:raise(Class, Reason, Stacktrace))</c>
and hope to distinguish exceptions later.</p>
</desc>
</func>
<func>
- <name>erlang:read_timer(TimerRef) -> int() | false</name>
+ <name>erlang:read_timer(TimerRef) -> integer() >= 0 | false</name>
<fsummary>Number of milliseconds remaining for a timer</fsummary>
<type>
- <v>TimerRef = ref()</v>
+ <v>TimerRef = reference()</v>
</type>
<desc>
<p><c>TimerRef</c> is a timer reference returned by
@@ -4039,7 +4194,7 @@ os_prompt%</pre>
<name>erlang:ref_to_list(Ref) -> string()</name>
<fsummary>Text representation of a reference</fsummary>
<type>
- <v>Ref = ref()</v>
+ <v>Ref = reference()</v>
</type>
<desc>
<p>Returns a string which corresponds to the text
@@ -4129,7 +4284,7 @@ true</pre>
</desc>
</func>
<func>
- <name>round(Number) -> int()</name>
+ <name>round(Number) -> integer()</name>
<fsummary>Return an integer by rounding a number</fsummary>
<type>
<v>Number = number()</v>
@@ -4213,12 +4368,12 @@ true</pre>
<name>erlang:send_after(Time, Dest, Msg) -> TimerRef</name>
<fsummary>Start a timer</fsummary>
<type>
- <v>Time = int()</v>
+ <v>Time = integer() >= 0</v>
<v>&nbsp;0 &lt;= Time &lt;= 4294967295</v>
<v>Dest = pid() | RegName </v>
<v>&nbsp;LocalPid = pid() (of a process, alive or dead, on the local node)</v>
<v>Msg = term()</v>
- <v>TimerRef = ref()</v>
+ <v>TimerRef = reference()</v>
</type>
<desc>
<p>Starts a timer which will send the message <c>Msg</c>
@@ -4242,17 +4397,12 @@ true</pre>
</desc>
</func>
<func>
- <name>erlang:send_nosuspend(Dest, Msg) -> bool()</name>
+ <name name="send_nosuspend" arity="2"/>
<fsummary>Try to send a message without ever blocking</fsummary>
- <type>
- <v>Dest = pid() | port() | RegName | {RegName, Node}</v>
- <v>&nbsp;RegName = atom()</v>
- <v>&nbsp;Node = node()</v>
- <v>Msg = term()</v>
- </type>
+ <type name="dst"/>
<desc>
<p>The same as
- <seealso marker="#send/3">erlang:send(Dest, Msg, [nosuspend])</seealso>, but returns <c>true</c> if
+ <seealso marker="#send/3">erlang:send(<anno>Dest</anno>, <anno>Msg</anno>, [nosuspend])</seealso>, but returns <c>true</c> if
the message was sent and <c>false</c> if the message was not
sent because the sender would have had to be suspended.</p>
<p>This function is intended for send operations towards an
@@ -4260,7 +4410,7 @@ true</pre>
(Erlang) process. If the connection to the remote node
(usually not a real Erlang node, but a node written in C or
Java) is overloaded, this function <em>will not send the message</em> but return <c>false</c> instead.</p>
- <p>The same happens, if <c>Dest</c> refers to a local port that
+ <p>The same happens, if <c><anno>Dest</anno></c> refers to a local port that
is busy. For all other destinations (allowed for the ordinary
send operator <c>'!'</c>) this function sends the message and
returns <c>true</c>.</p>
@@ -4293,18 +4443,12 @@ true</pre>
</desc>
</func>
<func>
- <name>erlang:send_nosuspend(Dest, Msg, Options) -> bool()</name>
+ <name name="send_nosuspend" arity="3"/>
<fsummary>Try to send a message without ever blocking</fsummary>
- <type>
- <v>Dest = pid() | port() | RegName | {RegName, Node}</v>
- <v>&nbsp;RegName = atom()</v>
- <v>&nbsp;Node = node()</v>
- <v>Msg = term()</v>
- <v>Option = noconnect</v>
- </type>
+ <type name="dst"/>
<desc>
<p>The same as
- <seealso marker="#send/3">erlang:send(Dest, Msg, [nosuspend | Options])</seealso>,
+ <seealso marker="#send/3">erlang:send(<anno>Dest</anno>, <anno>Msg</anno>, [nosuspend | <anno>Options</anno>])</seealso>,
but with boolean return value.</p>
<p>This function behaves like
<seealso marker="#send_nosuspend/2">erlang:send_nosuspend/2)</seealso>,
@@ -4329,17 +4473,13 @@ true</pre>
</desc>
</func>
<func>
- <name>erlang:set_cookie(Node, Cookie) -> true</name>
+ <name name="set_cookie" arity="2"/>
<fsummary>Set the magic cookie of a node</fsummary>
- <type>
- <v>Node = node()</v>
- <v>Cookie = atom()</v>
- </type>
<desc>
- <p>Sets the magic cookie of <c>Node</c> to the atom
- <c>Cookie</c>. If <c>Node</c> is the local node, the function
+ <p>Sets the magic cookie of <c><anno>Node</anno></c> to the atom
+ <c><anno>Cookie</anno></c>. If <c><anno>Node</anno></c> is the local node, the function
also sets the cookie of all other unknown nodes to
- <c>Cookie</c> (see
+ <c><anno>Cookie</anno></c> (see
<seealso marker="doc/reference_manual:distributed">Distributed Erlang</seealso> in the Erlang Reference Manual).</p>
<p>Failure: <c>function_clause</c> if the local node is not
alive.</p>
@@ -4364,7 +4504,7 @@ true</pre>
</desc>
</func>
<func>
- <name>size(Item) -> int()</name>
+ <name>size(Item) -> integer() >= 0</name>
<fsummary>Size of a tuple or binary</fsummary>
<type>
<v>Item = tuple() | binary()</v>
@@ -4379,28 +4519,21 @@ true</pre>
</desc>
</func>
<func>
- <name>spawn(Fun) -> pid()</name>
+ <name name="spawn" arity="1"/>
<fsummary>Create a new process with a fun as entry point</fsummary>
- <type>
- <v>Fun = fun()</v>
- </type>
<desc>
<p>Returns the pid of a new process started by the application
- of <c>Fun</c> to the empty list <c>[]</c>. Otherwise works
+ of <c><anno>Fun</anno></c> to the empty list <c>[]</c>. Otherwise works
like <seealso marker="#spawn/3">spawn/3</seealso>.</p>
</desc>
</func>
<func>
- <name>spawn(Node, Fun) -> pid()</name>
+ <name name="spawn" arity="2"/>
<fsummary>Create a new process with a fun as entry point on a given node</fsummary>
- <type>
- <v>Node = node()</v>
- <v>Fun = fun()</v>
- </type>
<desc>
<p>Returns the pid of a new process started by the application
- of <c>Fun</c> to the empty list <c>[]</c> on <c>Node</c>. If
- <c>Node</c> does not exist, a useless pid is returned.
+ of <c><anno>Fun</anno></c> to the empty list <c>[]</c> on <c><anno>Node</anno></c>. If
+ <c><anno>Node</anno></c> does not exist, a useless pid is returned.
Otherwise works like
<seealso marker="#spawn/3">spawn/3</seealso>.</p>
</desc>
@@ -4431,47 +4564,35 @@ true</pre>
</desc>
</func>
<func>
- <name>spawn(Node, Module, Function, ArgumentList) -> pid()</name>
+ <name name="spawn" arity="4"/>
<fsummary>Create a new process with a function as entry point on a given node</fsummary>
- <type>
- <v>Node = node()</v>
- <v>Module = Function = atom()</v>
- <v>Args = [term()]</v>
- </type>
<desc>
<p>Returns the pid of a new process started by the application
- of <c>Module:Function</c> to <c>Args</c> on <c>Node</c>. If
- <c>Node</c> does not exists, a useless pid is returned.
+ of <c><anno>Module</anno>:<anno>Function</anno></c> to <c><anno>Args</anno></c> on <c>Node</c>. If
+ <c><anno>Node</anno></c> does not exists, a useless pid is returned.
Otherwise works like
<seealso marker="#spawn/3">spawn/3</seealso>.</p>
</desc>
</func>
<func>
- <name>spawn_link(Fun) -> pid()</name>
+ <name name="spawn_link" arity="1"/>
<fsummary>Create and link to a new process with a fun as entry point</fsummary>
- <type>
- <v>Fun = fun()</v>
- </type>
<desc>
<p>Returns the pid of a new process started by the application
- of <c>Fun</c> to the empty list []. A link is created between
+ of <c><anno>Fun</anno></c> to the empty list []. A link is created between
the calling process and the new process, atomically.
Otherwise works like
<seealso marker="#spawn/3">spawn/3</seealso>.</p>
</desc>
</func>
<func>
- <name>spawn_link(Node, Fun) -> pid()</name>
+ <name name="spawn_link" arity="2"/>
<fsummary>Create and link to a new process with a fun as entry point on a specified node</fsummary>
- <type>
- <v>Node = node()</v>
- <v>Fun = fun()</v>
- </type>
<desc>
<p>Returns the pid of a new process started by the application
- of <c>Fun</c> to the empty list [] on <c>Node</c>. A link is
+ of <c><anno>Fun</anno></c> to the empty list [] on <c><anno>Node</anno></c>. A link is
created between the calling process and the new process,
- atomically. If <c>Node</c> does not exist, a useless pid is
+ atomically. If <c><anno>Node</anno></c> does not exist, a useless pid is
returned (and due to the link, an exit signal with exit
reason <c>noconnection</c> will be received). Otherwise works
like <seealso marker="#spawn/3">spawn/3</seealso>.</p>
@@ -4493,47 +4614,35 @@ true</pre>
</desc>
</func>
<func>
- <name>spawn_link(Node, Module, Function, Args) -> pid()</name>
+ <name name="spawn_link" arity="4"/>
<fsummary>Create and link to a new process with a function as entry point on a given node</fsummary>
- <type>
- <v>Node = node()</v>
- <v>Module = Function = atom()</v>
- <v>Args = [term()]</v>
- </type>
<desc>
<p>Returns the pid of a new process started by the application
- of <c>Module:Function</c> to <c>Args</c> on <c>Node</c>. A
+ of <c><anno>Module</anno>:<anno>Function</anno></c> to <c><anno>Args</anno></c> on <c>Node</c>. A
link is created between the calling process and the new
- process, atomically. If <c>Node</c> does not exist, a useless
+ process, atomically. If <c><anno>Node</anno></c> does not exist, a useless
pid is returned (and due to the link, an exit signal with exit
reason <c>noconnection</c> will be received). Otherwise works
like <seealso marker="#spawn/3">spawn/3</seealso>.</p>
</desc>
</func>
<func>
- <name>spawn_monitor(Fun) -> {pid(),reference()}</name>
+ <name name="spawn_monitor" arity="1"/>
<fsummary>Create and monitor a new process with a fun as entry point</fsummary>
- <type>
- <v>Fun = fun()</v>
- </type>
<desc>
<p>Returns the pid of a new process started by the application
- of <c>Fun</c> to the empty list [] and reference for a monitor
+ of <c><anno>Fun</anno></c> to the empty list [] and reference for a monitor
created to the new process.
Otherwise works like
<seealso marker="#spawn/3">spawn/3</seealso>.</p>
</desc>
</func>
<func>
- <name>spawn_monitor(Module, Function, Args) -> {pid(),reference()}</name>
+ <name name="spawn_monitor" arity="3"/>
<fsummary>Create and monitor a new process with a function as entry point</fsummary>
- <type>
- <v>Module = Function = atom()</v>
- <v>Args = [term()]</v>
- </type>
<desc>
<p>A new process is started by the application
- of <c>Module:Function</c> to <c>Args</c>, and the process is
+ of <c><anno>Module</anno>:<anno>Function</anno></c> to <c><anno>Args</anno></c>, and the process is
monitored at the same time. Returns the pid and a reference
for the monitor.
Otherwise works like
@@ -4541,19 +4650,11 @@ true</pre>
</desc>
</func>
<func>
- <name>spawn_opt(Fun, [Option]) -> pid() | {pid(),reference()}</name>
+ <name name="spawn_opt" arity="2"/>
<fsummary>Create a new process with a fun as entry point</fsummary>
- <type>
- <v>Fun = fun()</v>
- <v>Option = link | monitor | {priority, Level} | {fullsweep_after, Number} | {min_heap_size, Size} | {min_bin_vheap_size, VSize}</v>
- <v>&nbsp;Level = low | normal | high</v>
- <v>&nbsp;Number = int()</v>
- <v>&nbsp;Size = int()</v>
- <v>&nbsp;VSize = int()</v>
- </type>
<desc>
<p>Returns the pid of a new process started by the application
- of <c>Fun</c> to the empty list <c>[]</c>. Otherwise
+ of <c><anno>Fun</anno></c> to the empty list <c>[]</c>. Otherwise
works like
<seealso marker="#spawn_opt/4">spawn_opt/4</seealso>.</p>
<p>If the option <c>monitor</c> is given, the newly created
@@ -4562,37 +4663,19 @@ true</pre>
</desc>
</func>
<func>
- <name>spawn_opt(Node, Fun, [Option]) -> pid()</name>
+ <name name="spawn_opt" arity="3"/>
<fsummary>Create a new process with a fun as entry point on a given node</fsummary>
- <type>
- <v>Node = node()</v>
- <v>Fun = fun()</v>
- <v>Option = link | {priority, Level} | {fullsweep_after, Number} | {min_heap_size, Size} | {min_bin_vheap_size, VSize}</v>
- <v>&nbsp;Level = low | normal | high</v>
- <v>&nbsp;Number = int()</v>
- <v>&nbsp;Size = int()</v>
- <v>&nbsp;VSize = int()</v>
- </type>
<desc>
<p>Returns the pid of a new process started by the application
- of <c>Fun</c> to the empty list <c>[]</c> on <c>Node</c>. If
- <c>Node</c> does not exist, a useless pid is returned.
+ of <c><anno>Fun</anno></c> to the empty list <c>[]</c> on <c><anno>Node</anno></c>. If
+ <c><anno>Node</anno></c> does not exist, a useless pid is returned.
Otherwise works like
<seealso marker="#spawn_opt/4">spawn_opt/4</seealso>.</p>
</desc>
</func>
<func>
- <name>spawn_opt(Module, Function, Args, [Option]) -> pid() | {pid(),reference()}</name>
+ <name name="spawn_opt" arity="4"/>
<fsummary>Create a new process with a function as entry point</fsummary>
- <type>
- <v>Module = Function = atom()</v>
- <v>Args = [term()]</v>
- <v>Option = link | monitor | {priority, Level} | {fullsweep_after, Number} | {min_heap_size, Size} | {min_bin_vheap_size, VSize}</v>
- <v>&nbsp;Level = low | normal | high</v>
- <v>&nbsp;Number = int()</v>
- <v>&nbsp;Size = int()</v>
- <v>&nbsp;VSize = int()</v>
- </type>
<desc>
<p>Works exactly like
<seealso marker="#spawn/3">spawn/3</seealso>, except that an
@@ -4609,19 +4692,19 @@ true</pre>
<tag><c>monitor</c></tag>
<item>
<p>Monitor the new process (just like
- <seealso marker="#monitor/2">erlang:monitor/2</seealso> does).</p>
+ <seealso marker="#monitor/2">monitor/2</seealso> does).</p>
</item>
- <tag><c>{priority, Level}</c></tag>
+ <tag><c>{priority, <anno>Level</anno>}</c></tag>
<item>
<p>Sets the priority of the new process. Equivalent to
executing
- <seealso marker="#process_flag_priority">process_flag(priority, Level)</seealso> in the start function of the new process,
+ <seealso marker="#process_flag_priority">process_flag(priority, <anno>Level</anno>)</seealso> in the start function of the new process,
except that the priority will be set before the process is
selected for execution for the first time. For more information
on priorities see
<seealso marker="#process_flag_priority">process_flag(priority, Level)</seealso>.</p>
</item>
- <tag><c>{fullsweep_after, Number}</c></tag>
+ <tag><c>{fullsweep_after, <anno>Number</anno>}</c></tag>
<item>
<p>This option is only useful for performance tuning.
In general, you should not use this option unless you
@@ -4643,18 +4726,18 @@ true</pre>
<p>Here are a few cases when it could be useful to change
<c>fullsweep_after</c>. Firstly, if binaries that are no
longer used should be thrown away as soon as possible.
- (Set <c>Number</c> to zero.) Secondly, a process that
+ (Set <c><anno>Number</anno></c> to zero.) Secondly, a process that
mostly have short-lived data will be fullsweeped seldom
or never, meaning that the old heap will contain mostly
garbage. To ensure a fullsweep once in a while, set
- <c>Number</c> to a suitable value such as 10 or 20.
+ <c><anno>Number</anno></c> to a suitable value such as 10 or 20.
Thirdly, in embedded systems with limited amount of RAM
and no virtual memory, one might want to preserve memory
- by setting <c>Number</c> to zero. (The value may be set
+ by setting <c><anno>Number</anno></c> to zero. (The value may be set
globally, see
<seealso marker="#system_flag/2">erlang:system_flag/2</seealso>.)</p>
</item>
- <tag><c>{min_heap_size, Size}</c></tag>
+ <tag><c>{min_heap_size, <anno>Size</anno>}</c></tag>
<item>
<p>This option is only useful for performance tuning.
In general, you should not use this option unless you
@@ -4669,9 +4752,9 @@ true</pre>
slow down the system due to worse data locality.
Therefore, it is recommended to use this option only for
fine-tuning an application and to measure the execution
- time with various <c>Size</c> values.</p>
+ time with various <c><anno>Size</anno></c> values.</p>
</item>
- <tag><c>{min_bin_vheap_size, VSize}</c></tag>
+ <tag><c>{min_bin_vheap_size, <anno>VSize</anno>}</c></tag>
<item>
<p>This option is only useful for performance tuning.
In general, you should not use this option unless you
@@ -4685,29 +4768,19 @@ true</pre>
Setting too high value, however, might waste memory.
Therefore, it is recommended to use this option only for
fine-tuning an application and to measure the execution
- time with various <c>VSize</c> values.</p>
+ time with various <c><anno>VSize</anno></c> values.</p>
</item>
</taglist>
</desc>
</func>
<func>
- <name>spawn_opt(Node, Module, Function, Args, [Option]) -> pid()</name>
+ <name name="spawn_opt" arity="5"/>
<fsummary>Create a new process with a function as entry point on a given node</fsummary>
- <type>
- <v>Node = node()</v>
- <v>Module = Function = atom()</v>
- <v>Args = [term()]</v>
- <v>Option = link | {priority, Level} | {fullsweep_after, Number} | {min_heap_size, Size} | {min_bin_vheap_size, VSize}</v>
- <v>&nbsp;Level = low | normal | high</v>
- <v>&nbsp;Number = int()</v>
- <v>&nbsp;Size = int()</v>
- <v>&nbsp;VSize = int()</v>
- </type>
<desc>
<p>Returns the pid of a new process started by the application
- of <c>Module:Function</c> to <c>Args</c> on <c>Node</c>. If
- <c>Node</c> does not exist, a useless pid is returned.
+ of <c><anno>Module</anno>:<anno>Function</anno></c> to <c><anno>Args</anno></c> on <c>Node</c>. If
+ <c><anno>Node</anno></c> does not exist, a useless pid is returned.
Otherwise works like
<seealso marker="#spawn_opt/4">spawn_opt/4</seealso>.</p>
</desc>
@@ -4741,13 +4814,13 @@ true</pre>
<name>erlang:start_timer(Time, Dest, Msg) -> TimerRef</name>
<fsummary>Start a timer</fsummary>
<type>
- <v>Time = int()</v>
+ <v>Time = integer() >= 0</v>
<v>&nbsp;0 &lt;= Time &lt;= 4294967295</v>
<v>Dest = LocalPid | RegName </v>
<v>&nbsp;LocalPid = pid() (of a process, alive or dead, on the local node)</v>
<v>&nbsp;RegName = atom()</v>
<v>Msg = term()</v>
- <v>TimerRef = ref()</v>
+ <v>TimerRef = reference()</v>
</type>
<desc>
<p>Starts a timer which will send the message
@@ -4850,7 +4923,7 @@ true</pre>
</desc>
</func>
<func>
- <name>erlang:suspend_process(Suspendee, OptList) -> true | false</name>
+ <name>erlang:suspend_process(Suspendee, OptList) -> boolean()</name>
<fsummary>Suspend a process</fsummary>
<type>
<v>Suspendee = pid()</v>
@@ -4950,15 +5023,12 @@ true</pre>
</desc>
</func>
<func>
- <name>erlang:suspend_process(Suspendee) -> true</name>
+ <name name="suspend_process" arity="1"/>
<fsummary>Suspend a process</fsummary>
- <type>
- <v>Suspendee = pid()</v>
- </type>
<desc>
- <p>Suspends the process identified by <c>Suspendee</c>. The
+ <p>Suspends the process identified by <c><anno>Suspendee</anno></c>. The
same as calling
- <seealso marker="#suspend_process/2">erlang:suspend_process(Suspendee, [])</seealso>. For more information see the documentation of <seealso marker="#suspend_process/2">erlang:suspend_process/2</seealso>.
+ <seealso marker="#suspend_process/2">erlang:suspend_process(<anno>Suspendee</anno>, [])</seealso>. For more information see the documentation of <seealso marker="#suspend_process/2">erlang:suspend_process/2</seealso>.
</p>
<warning>
<p>This BIF is intended for debugging only.</p>
@@ -5093,9 +5163,9 @@ true</pre>
schedulers actually have bound as requested, call
<seealso marker="#system_info_scheduler_bindings">erlang:system_info(scheduler_bindings)</seealso>.
</p>
- <p>Schedulers can currently only be bound on newer Linux
- and Solaris systems, but more systems will be supported
- in the future.
+ <p>Schedulers can currently only be bound on newer Linux,
+ Solaris, FreeBSD, and Windows systems, but more systems will be
+ supported in the future.
</p>
<p>In order for the runtime system to be able to bind schedulers,
the CPU topology needs to be known. If the runtime system fails
@@ -5103,10 +5173,21 @@ true</pre>
For more information on how to define the CPU topology, see
<seealso marker="#system_flag_cpu_topology">erlang:system_flag(cpu_topology, CpuTopology)</seealso>.
</p>
- <p><em>NOTE:</em> If other programs on the system have bound
- to processors, e.g. another Erlang runtime system, you
- may loose performance when binding schedulers. Therefore,
- schedulers are by default not bound.</p>
+ <p>The runtime system will by default bind schedulers to logical
+ processors using the <c>default_bind</c> bind type if the amount
+ of schedulers are at least equal to the amount of logical
+ processors configured, binding of schedulers is supported,
+ and a CPU topology is available at startup.
+ </p>
+ <p><em>NOTE:</em> If the Erlang runtime system is the only
+ operating system process that binds threads to logical processors,
+ this improves the performance of the runtime system. However,
+ if other operating system processes (as for example another Erlang
+ runtime system) also bind threads to logical processors, there
+ might be a performance penalty instead. If this is the case you,
+ are are advised to unbind the schedulers using the
+ <seealso marker="erl#+sbt">+sbtu</seealso> command line argument,
+ or <c>erlang:system_flag(scheduler_bind_type, unbound)</c>.</p>
<p>Schedulers can be bound in different ways. The <c>How</c>
argument determines how schedulers are bound. <c>How</c> can
currently be one of:</p>
@@ -5271,8 +5352,8 @@ true</pre>
<p>Returns <c>{Allocator, Version, Features, Settings}.</c></p>
<p>Types:</p>
<list type="bulleted">
- <item><c>Allocator = undefined | elib_malloc | glibc</c></item>
- <item><c>Version = [int()]</c></item>
+ <item><c>Allocator = undefined | glibc</c></item>
+ <item><c>Version = [integer()]</c></item>
<item><c>Features = [atom()]</c></item>
<item><c>Settings = [{Subsystem, [{Parameter, Value}]}]</c></item>
<item><c>Subsystem = atom()</c></item>
@@ -5286,7 +5367,7 @@ true</pre>
implementation used. If <c>Allocator</c> equals
<c>undefined</c>, the <c>malloc()</c> implementation
used could not be identified. Currently
- <c>elib_malloc</c> and <c>glibc</c> can be identified.</p>
+ <c>glibc</c> can be identified.</p>
</item>
<item>
<p><c>Version</c> is a list of integers (but not a
@@ -5363,6 +5444,16 @@ true</pre>
<seealso marker="#system_info_allocator_tuple">erlang:system_info({allocator, Alloc})</seealso>.
</p>
</item>
+ <tag><c>build_type</c></tag>
+ <item>
+ <p>Returns an atom describing the build type of the runtime
+ system. This is normally the atom <c>opt</c> for optimized.
+ Other possible return values are <c>debug</c>, <c>purify</c>,
+ <c>quantify</c>, <c>purecov</c>, <c>gcov</c>, <c>valgrind</c>,
+ <c>gprof</c>, and <c>lcnt</c>. Possible return values
+ may be added and/or removed at any time without prior notice.
+ </p>
+ </item>
<tag><c>c_compiler_used</c></tag>
<item>
<p>Returns a two-tuple describing the C compiler used when
@@ -5440,7 +5531,7 @@ true</pre>
<c>CpuTopology</c> type to change.
</p>
</item>
- <tag><c>{cpu_topology, defined}</c></tag>
+ <tag><marker id="system_info_cpu_topology_defined"><c>{cpu_topology, defined}</c></marker></tag>
<item>
<p>Returns the user defined <c>CpuTopology</c>. For more
information see the documentation of
@@ -5450,12 +5541,14 @@ true</pre>
argument.
</p>
</item>
- <tag><c>{cpu_topology, detected}</c></tag>
+ <tag><marker id="system_info_cpu_topology_detected"><c>{cpu_topology, detected}</c></marker></tag>
<item>
<p>Returns the automatically detected <c>CpuTopology</c>. The
emulator currently only detects the CPU topology on some newer
- linux and solaris systems. For more information see the
- documentation of the
+ Linux, Solaris, FreeBSD, and Windows systems. On Windows system with
+ more than 32 logical processors the CPU topology is not detected.
+ </p>
+ <p>For more information see the documentation of the
<seealso marker="#system_info_cpu_topology">cpu_topology</seealso>
argument.
</p>
@@ -5513,56 +5606,20 @@ true</pre>
</item>
<tag><c>elib_malloc</c></tag>
<item>
- <p>If the emulator uses the <c>elib_malloc</c> memory
- allocator, a list of two-element tuples containing status
- information is returned; otherwise, <c>false</c> is
- returned. The list currently contains the following
- two-element tuples (all sizes are presented in bytes):</p>
- <taglist>
- <tag><c>{heap_size, Size}</c></tag>
- <item>
- <p>Where <c>Size</c> is the current heap size.</p>
- </item>
- <tag><c>{max_alloced_size, Size}</c></tag>
- <item>
- <p>Where <c>Size</c> is the maximum amount of memory
- allocated on the heap since the emulator started.</p>
- </item>
- <tag><c>{alloced_size, Size}</c></tag>
- <item>
- <p>Where <c>Size</c> is the current amount of memory
- allocated on the heap.</p>
- </item>
- <tag><c>{free_size, Size}</c></tag>
- <item>
- <p>Where <c>Size</c> is the current amount of free
- memory on the heap.</p>
- </item>
- <tag><c>{no_alloced_blocks, No}</c></tag>
- <item>
- <p>Where <c>No</c> is the current number of allocated
- blocks on the heap.</p>
- </item>
- <tag><c>{no_free_blocks, No}</c></tag>
- <item>
- <p>Where <c>No</c> is the current number of free blocks
- on the heap.</p>
- </item>
- <tag><c>{smallest_alloced_block, Size}</c></tag>
- <item>
- <p>Where <c>Size</c> is the size of the smallest
- allocated block on the heap.</p>
- </item>
- <tag><c>{largest_free_block, Size}</c></tag>
- <item>
- <p>Where <c>Size</c> is the size of the largest free
- block on the heap.</p>
- </item>
- </taglist>
+ <p>This option will be removed in a future release.
+ The return value will always be <c>false</c> since
+ the elib_malloc allocator has been removed.</p>
+ </item>
+ <tag><marker id="system_info_dist_buf_busy_limit"><c>dist_buf_busy_limit</c></marker></tag>
+ <item>
+ <p>Returns the value of the distribution buffer busy limit
+ in bytes. This limit can be set on startup by passing the
+ <seealso marker="erl#+zdbbl">+zdbbl</seealso> command line
+ flag to <c>erl</c>.</p>
</item>
<tag><c>fullsweep_after</c></tag>
<item>
- <p>Returns <c>{fullsweep_after, int()}</c> which is the
+ <p>Returns <c>{fullsweep_after, integer()}</c> which is the
<c>fullsweep_after</c> garbage collection setting used
by default. For more information see
<c>garbage_collection</c> described below.</p>
@@ -5634,11 +5691,34 @@ true</pre>
information see the <seealso marker="erts:crash_dump">"How to interpret the Erlang crash dumps"</seealso> chapter
in the ERTS User's Guide.</p>
</item>
- <tag><c>logical_processors</c></tag>
+ <tag><marker id="logical_processors"><c>logical_processors</c></marker></tag>
+ <item>
+ <p>Returns the detected number of logical processors configured
+ on the system. The return value is either an integer, or
+ the atom <c>unknown</c> if the emulator wasn't able to
+ detect logical processors configured.
+ </p>
+ </item>
+ <tag><marker id="logical_processors_available"><c>logical_processors_available</c></marker></tag>
<item>
- <p>Returns the number of logical processors detected on the
- system as an integer or the atom <c>unknown</c> if the
- emulator wasn't able to detect any.
+ <p>Returns the detected number of logical processors available to
+ the Erlang runtime system. The return value is either an
+ integer, or the atom <c>unknown</c> if the emulator wasn't
+ able to detect logical processors available. The number
+ of logical processors available is less than or equal to
+ the number of <seealso marker="#logical_processors_online">logical
+ processors online</seealso>.
+ </p>
+ </item>
+ <tag><marker id="logical_processors_online"><c>logical_processors_online</c></marker></tag>
+ <item>
+ <p>Returns the detected number of logical processors online on
+ the system. The return value is either an integer,
+ or the atom <c>unknown</c> if the emulator wasn't able to
+ detect logical processors online. The number of logical
+ processors online is less than or equal to the number of
+ <seealso marker="#logical_processors">logical processors
+ configured</seealso>.
</p>
</item>
<tag><c>machine</c></tag>
@@ -5843,6 +5923,26 @@ true</pre>
<c>get_tcw</c> in "Match Specifications in Erlang",
<seealso marker="erts:match_spec#get_tcw">ERTS User's Guide</seealso>.</p>
</item>
+ <tag><marker id="update_cpu_info"><c>update_cpu_info</c></marker></tag>
+ <item>
+ <p>The runtime system rereads the CPU information available and
+ updates its internally stored information about the
+ <seealso marker="#system_info_cpu_topology_detected">detected CPU
+ topology</seealso> and the amount of logical processors
+ <seealso marker="#logical_processors">configured</seealso>,
+ <seealso marker="#logical_processors_online">online</seealso>, and
+ <seealso marker="#logical_processors_available">available</seealso>.
+ If the CPU information has changed since the last time it was read,
+ the atom <c>changed</c> is returned; otherwise, the atom
+ <c>unchanged</c> is returned. If the CPU information has changed
+ you probably want to
+ <seealso marker="#system_flag_schedulers_online">adjust the amount
+ of schedulers online</seealso>. You typically want to have as
+ many schedulers online as
+ <seealso marker="#logical_processors_available">logical processors
+ available</seealso>.
+ </p>
+ </item>
<tag><marker id="system_info_version"><c>version</c></marker></tag>
<item>
<p>Returns a string containing the version number of the
@@ -5850,9 +5950,23 @@ true</pre>
</item>
<tag><c>wordsize</c></tag>
<item>
- <p>Returns the word size in bytes as an integer, i.e. on a
- 32-bit architecture 4 is returned, and on a 64-bit
- architecture 8 is returned.</p>
+ <p>Same as <c>{wordsize, internal}.</c></p>
+ </item>
+ <tag><c>{wordsize, internal}</c></tag>
+ <item>
+ <p>Returns the size of Erlang term words in bytes as an
+ integer, i.e. on a 32-bit architecture 4 is returned,
+ and on a pure 64-bit architecture 8 is returned. On a
+ halfword 64-bit emulator, 4 is returned, as the Erlang
+ terms are stored using a virtual wordsize of half the
+ system's wordsize.</p>
+ </item>
+ <tag><c>{wordsize, external}</c></tag>
+ <item>
+ <p>Returns the true wordsize of the emulator, i.e. the size
+ of a pointer, in bytes as an integer. On a pure 32-bit
+ architecture 4 is returned, on both a halfword and pure
+ 64-bit architecture, 8 is returned.</p>
</item>
</taglist>
<note>
@@ -5873,7 +5987,7 @@ true</pre>
<v>&nbsp;MonitorPid = pid()</v>
<v>&nbsp;Options = [Option]</v>
<v>&nbsp;&nbsp;Option = {long_gc, Time} | {large_heap, Size} | busy_port | busy_dist_port</v>
- <v>&nbsp;&nbsp;&nbsp;Time = Size = int()</v>
+ <v>&nbsp;&nbsp;&nbsp;Time = Size = integer()</v>
</type>
<desc>
<p>Returns the current system monitoring settings set by
@@ -5907,7 +6021,7 @@ true</pre>
<type>
<v>MonitorPid = pid()</v>
<v>Option = {long_gc, Time} | {large_heap, Size} | busy_port | busy_dist_port</v>
- <v>&nbsp;Time = Size = int()</v>
+ <v>&nbsp;Time = Size = integer()</v>
<v>MonSettings = {OldMonitorPid, [Option]}</v>
<v>&nbsp;OldMonitorPid = pid()</v>
</type>
@@ -6137,7 +6251,7 @@ true</pre>
<name>time() -> {Hour, Minute, Second}</name>
<fsummary>Current time</fsummary>
<type>
- <v>Hour = Minute = Second = int()</v>
+ <v>Hour = Minute = Second = integer() >= 0</v>
</type>
<desc>
<p>Returns the current time as <c>{Hour, Minute, Second}</c>.</p>
@@ -6165,11 +6279,11 @@ true</pre>
</desc>
</func>
<func>
- <name>erlang:trace(PidSpec, How, FlagList) -> int()</name>
+ <name>erlang:trace(PidSpec, How, FlagList) -> integer() >= 0</name>
<fsummary>Set trace flags for a process or processes</fsummary>
<type>
<v>PidSpec = pid() | existing | new | all</v>
- <v>How = bool()</v>
+ <v>How = boolean()</v>
<v>FlagList = [Flag]</v>
<v>&nbsp;Flag -- see below</v>
</type>
@@ -6570,7 +6684,7 @@ true</pre>
<type>
<v>PidOrFunc = pid() | new | {Module, Function, Arity} | on_load</v>
<v>&nbsp;Module = Function = atom()</v>
- <v>&nbsp;Arity = int()</v>
+ <v>&nbsp;Arity = arity()</v>
<v>Item, Res -- see below</v>
</type>
<desc>
@@ -6645,6 +6759,17 @@ true</pre>
See also
<seealso marker="#trace_pattern/3">erlang:trace_pattern/3</seealso>.</p>
</item>
+ <tag><c>call_time</c></tag>
+ <item>
+ <p>Return the call time values for this function or
+ <c>true</c> for the pseudo function <c>on_load</c> if call
+ time tracing is active. Returns <c>false</c> otherwise.
+ The call time values returned, <c>[{Pid, Count, S, Us}]</c>,
+ is a list of each process that has executed the function and its specific counters.
+ See also
+ <seealso marker="#trace_pattern/3">erlang:trace_pattern/3</seealso>.</p>
+ </item>
+
<tag><c>all</c></tag>
<item>
<p>Return a list containing the <c>{Item, Value}</c> tuples
@@ -6662,7 +6787,7 @@ true</pre>
</desc>
</func>
<func>
- <name>erlang:trace_pattern(MFA, MatchSpec) -> int()</name>
+ <name>erlang:trace_pattern(MFA, MatchSpec) -> integer() >= 0</name>
<fsummary>Set trace patterns for global call tracing</fsummary>
<desc>
<p>The same as
@@ -6671,7 +6796,7 @@ true</pre>
</desc>
</func>
<func>
- <name>erlang:trace_pattern(MFA, MatchSpec, FlagList) -> int()</name>
+ <name>erlang:trace_pattern(MFA, MatchSpec, FlagList) -> integer() >= 0</name>
<fsummary>Set trace patterns for tracing of function calls</fsummary>
<type>
<v>MFA, MatchSpec, FlagList -- see below</v>
@@ -6747,13 +6872,13 @@ true</pre>
</item>
<tag><c>restart</c></tag>
<item>
- <p>For the <c>FlagList</c> option <c>call_count</c>:
+ <p>For the <c>FlagList</c> option <c>call_count</c> and <c>call_time</c>:
restart the existing counters. The behaviour is undefined
for other <c>FlagList</c> options.</p>
</item>
<tag><c>pause</c></tag>
<item>
- <p>For the <c>FlagList</c> option <c>call_count</c>: pause
+ <p>For the <c>FlagList</c> option <c>call_count</c> and <c>call_time</c>: pause
the existing counters. The behaviour is undefined for
other <c>FlagList</c> options.</p>
</item>
@@ -6808,6 +6933,23 @@ true</pre>
<p>The counter value can be read with
<seealso marker="#trace_info/2">erlang:trace_info/2</seealso>.</p>
</item>
+ <tag><c>call_time</c></tag>
+ <item>
+ <p>Starts (<c>MatchSpec == true</c>) or stops
+ (<c>MatchSpec == false</c>) call time tracing for all
+ types of function calls. For every function a counter is
+ incremented when the function is called. Time spent in the function
+ is accumulated in two other counters, seconds and micro-seconds.
+ The counters are stored for each call traced process.</p>
+ <p>If call time tracing is started while already running,
+ the count and time is restarted from zero. Running counters can be
+ paused with <c>MatchSpec == pause</c>. Paused and running
+ counters can be restarted from zero with
+ <c>MatchSpec == restart</c>.</p>
+ <p>The counter value can be read with
+ <seealso marker="#trace_info/2">erlang:trace_info/2</seealso>.</p>
+ </item>
+
</taglist>
<p>The <c>global</c> and <c>local</c> options are mutually
exclusive and <c>global</c> is the default (if no options are
@@ -6815,7 +6957,7 @@ true</pre>
perform a kind of local tracing, and can also not be combined
with <c>global</c>. A function can be either globally or
locally traced. If global tracing is specified for a
- specified set of functions; local, meta and call count
+ specified set of functions; local, meta, call time and call count
tracing for the matching set of local functions will be
disabled, and vice versa.</p>
<p>When disabling trace, the option must match the type of trace
@@ -6834,7 +6976,7 @@ true</pre>
</desc>
</func>
<func>
- <name>trunc(Number) -> int()</name>
+ <name>trunc(Number) -> integer()</name>
<fsummary>Return an integer by the truncating a number</fsummary>
<type>
<v>Number = number()</v>
@@ -6848,7 +6990,7 @@ true</pre>
</desc>
</func>
<func>
- <name>tuple_size(Tuple) -> int()</name>
+ <name>tuple_size(Tuple) -> integer() >= 0</name>
<fsummary>Return the size of a tuple</fsummary>
<type>
<v>Tuple = tuple()</v>
@@ -6876,12 +7018,10 @@ true</pre>
</desc>
</func>
<func>
- <name>erlang:universaltime() -> {Date, Time}</name>
+ <name>erlang:universaltime() -> DateTime</name>
<fsummary>Current date and time according to Universal Time Coordinated (UTC)</fsummary>
<type>
- <v>Date = {Year, Month, Day}</v>
- <v>Time = {Hour, Minute, Second}</v>
- <v>&nbsp;Year = Month = Day = Hour = Minute = Second = int()</v>
+ <v>DateTime = <seealso marker="calendar#type-datetime">calendar:datetime()</seealso></v>
</type>
<desc>
<p>Returns the current date and time according to Universal
@@ -6899,9 +7039,8 @@ true</pre>
<name>erlang:universaltime_to_localtime({Date1, Time1}) -> {Date2, Time2}</name>
<fsummary>Convert from Universal Time Coordinated (UTC) to local date and time</fsummary>
<type>
- <v>Date1 = Date2 = {Year, Month, Day}</v>
- <v>Time1 = Time2 = {Hour, Minute, Second}</v>
- <v>&nbsp;Year = Month = Day = Hour = Minute = Second = int()</v>
+ <v>Date1 = Date2 = <seealso marker="calendar#type-date">calendar:date()</seealso></v>
+ <v>Time1 = Time2 = <seealso marker="calendar#type-time">calendar:time()</seealso></v>
</type>
<desc>
<p>Converts Universal Time Coordinated (UTC) date and time to
@@ -6988,7 +7127,7 @@ true</pre>
</desc>
</func>
<func>
- <name>erlang:yield() -> true</name>
+ <name name="yield" arity="0"/>
<fsummary>Let other processes get a chance to execute</fsummary>
<desc>
<p>Voluntarily let other processes (if any) get a chance to
diff --git a/erts/doc/src/erlc.xml b/erts/doc/src/erlc.xml
index 1e8960c22c..ebf76a2afe 100644
--- a/erts/doc/src/erlc.xml
+++ b/erts/doc/src/erlc.xml
@@ -4,7 +4,7 @@
<comref>
<header>
<copyright>
- <year>1997</year><year>2010</year>
+ <year>1997</year><year>2011</year>
<holder>Ericsson AB. All Rights Reserved.</holder>
</copyright>
<legalnotice>
@@ -141,6 +141,50 @@
for compiling native code, which needs to be compiled with the same
run-time system that it should be run on.</p>
</item>
+ <tag>-M</tag>
+ <item>
+ <p>Produces a Makefile rule to track headers dependencies. The
+ rule is sent to stdout. No object file is produced.
+ </p>
+ </item>
+ <tag>-MF <em>Makefile</em></tag>
+ <item>
+ <p>Like the <c><![CDATA[-M]]></c> option above, except that the
+ Makefile is written to <em>Makefile</em>. No object
+ file is produced.
+ </p>
+ </item>
+ <tag>-MD</tag>
+ <item>
+ <p>Same as <c><![CDATA[-M -MF <File>.Pbeam]]></c>.
+ </p>
+ </item>
+ <tag>-MT <em>Target</em></tag>
+ <item>
+ <p>In conjunction with <c><![CDATA[-M]]></c> or
+ <c><![CDATA[-MF]]></c>, change the name of the rule emitted
+ to <em>Target</em>.
+ </p>
+ </item>
+ <tag>-MQ <em>Target</em></tag>
+ <item>
+ <p>Like the <c><![CDATA[-MT]]></c> option above, except that
+ characters special to make(1) are quoted.
+ </p>
+ </item>
+ <tag>-MP</tag>
+ <item>
+ <p>In conjunction with <c><![CDATA[-M]]></c> or
+ <c><![CDATA[-MF]]></c>, add a phony target for each dependency.
+ </p>
+ </item>
+ <tag>-MG</tag>
+ <item>
+ <p>In conjunction with <c><![CDATA[-M]]></c> or
+ <c><![CDATA[-MF]]></c>, consider missing headers as generated
+ files and add them to the dependencies.
+ </p>
+ </item>
<tag>--</tag>
<item>
<p>Signals that no more options will follow.
diff --git a/erts/doc/src/erlsrv.xml b/erts/doc/src/erlsrv.xml
index 0dfad2a112..c1ecbc7b77 100644
--- a/erts/doc/src/erlsrv.xml
+++ b/erts/doc/src/erlsrv.xml
@@ -4,7 +4,7 @@
<comref>
<header>
<copyright>
- <year>1998</year><year>2010</year>
+ <year>1998</year><year>2011</year>
<holder>Ericsson AB. All Rights Reserved.</holder>
</copyright>
<legalnotice>
@@ -273,7 +273,7 @@
</desc>
</func>
<func>
- <name>erlsrv {start | stop | disable | enable} &lt;service-name></name>
+ <name>erlsrv {start | start_disabled | stop | disable | enable} &lt;service-name></name>
<fsummary>Manipulate the current service status.</fsummary>
<desc>
<p>These commands are only added for convenience, the normal
@@ -287,6 +287,21 @@
service actually is stopped. Enabling a service sets it in
automatic mode, that is started at boot. This command cannot
set the service to manual. </p>
+
+ <p>The <c>start_disabled</c> command operates on a service
+ regardless of if it's enabled/disabled or started/stopped. It
+ does this by first enabling it (regardless of if it's enabled
+ or not), then starting it (if it's not already started) and
+ then disabling it. The result will be a disabled but started
+ service, regardless of its earlier state. This is useful for
+ starting services temporarily during a release upgrade. The
+ difference between using <c>start_disabled</c> and the
+ sequence <c>enable</c>, <c>start</c> and <c>disable</c> is
+ that all other <c>erlsrv</c> commands are locked out during
+ the sequence of operations in <c>start_disable</c>, making the
+ operation atomic from an <c>erlsrv</c> user's point of
+ view.</p>
+
</desc>
</func>
<func>
diff --git a/erts/doc/src/erts_alloc.xml b/erts/doc/src/erts_alloc.xml
index 51a4a2bca0..86e1e5168a 100644
--- a/erts/doc/src/erts_alloc.xml
+++ b/erts/doc/src/erts_alloc.xml
@@ -4,7 +4,7 @@
<cref>
<header>
<copyright>
- <year>2002</year><year>2010</year>
+ <year>2002</year><year>2011</year>
<holder>Ericsson AB. All Rights Reserved.</holder>
</copyright>
<legalnotice>
@@ -78,14 +78,20 @@
segments are allocated, cached segments are used if possible
instead of creating new segments. This in order to reduce
the number of system calls made.</item>
+ <tag><c>sbmbc_alloc</c></tag>
+ <item>Allocator used by other allocators for allocation of carriers
+ where only small blocks are placed. Currently this allocator is
+ disabled by default.</item>
</taglist>
<p><c>sys_alloc</c> and <c>fix_alloc</c> are always enabled and
cannot be disabled. <c>mseg_alloc</c> is always enabled if it is
available and an allocator that uses it is enabled. All other
allocators can be <seealso marker="#M_e">enabled or disabled</seealso>.
By default all allocators are enabled.
- When an allocator is disabled, <c>sys_alloc</c>
- is used instead of the disabled allocator.</p>
+ When an allocator is disabled, <c>sys_alloc</c> is used instead of
+ the disabled allocator. <c>sbmbc_alloc</c> is an exception. If
+ <c>sbmbc_alloc</c> is disabled, other allocators will not handle
+ small blocks in separate carriers.</p>
<p>The main idea with the <c>erts_alloc</c> library is to separate
memory blocks that are used differently into different memory
areas, and by this achieving less memory fragmentation. By
@@ -103,21 +109,25 @@
following does <em>not</em> apply to them.</p>
<p>An allocator manages multiple areas, called carriers, in which
memory blocks are placed. A carrier is either placed in a
- separate memory segment (allocated via <c>mseg_alloc</c>) or in
- the heap segment (allocated via <c>sys_alloc</c>). Multiblock
+ separate memory segment (allocated via <c>mseg_alloc</c>), in
+ the heap segment (allocated via <c>sys_alloc</c>), or inside
+ another carrier (in case it is a carrier created by
+ <c>sbmbc_alloc</c>). Multiblock
carriers are used for storage of several blocks. Singleblock
carriers are used for storage of one block. Blocks that are
larger than the value of the singleblock carrier threshold
(<seealso marker="#M_sbct">sbct</seealso>) parameter are placed
- in singleblock carriers. Blocks smaller than the value of the
- <c>sbct</c> parameter are placed in multiblock
- carriers. Normally an allocator creates a "main multiblock
+ in singleblock carriers. Blocks that are smaller than the value
+ of the <c>sbct</c> parameter are placed in multiblock
+ carriers. Blocks that are smaller than the small block multiblock
+ carrier threshold (<seealso marker="#M_sbmbct">sbmbct</seealso>)
+ will be placed in multiblock carriers only used for small blocks.
+ Normally an allocator creates a "main multiblock
carrier". Main multiblock carriers are never deallocated. The
size of the main multiblock carrier is determined by the value
of the <seealso marker="#M_mmbcs">mmbcs</seealso> parameter.</p>
- <p> <marker id="mseg_mbc_sizes"></marker>
-
- Sizes of multiblock carriers allocated via <c>mseg_alloc</c> are
+ <p><marker id="mseg_mbc_sizes"></marker>Sizes of multiblock carriers
+ allocated via <c>mseg_alloc</c> are
decided based on the values of the largest multiblock carrier
size (<seealso marker="#M_lmbcs">lmbcs</seealso>), the smallest
multiblock carrier size (<seealso marker="#M_smbcs">smbcs</seealso>),
@@ -133,8 +143,11 @@
<c>sbct</c> parameter should be larger than the value of the
<c>lmbcs</c> parameter, the allocator may have to create
multiblock carriers that are larger than the value of the
- <c>lmbcs</c> parameter, though. Singleblock carriers allocated
- via <c>mseg_alloc</c> are sized to whole pages.</p>
+ <c>lmbcs</c> parameter, though. The size of multiblock carriers
+ for small blocks is determined by the small block multiblock
+ carrier size (<seealso marker="#M_sbmbcs">sbmbcs</seealso>).
+ Singleblock carriers allocated via <c>mseg_alloc</c> are sized
+ to whole pages.</p>
<p>Sizes of carriers allocated via <c>sys_alloc</c> are
decided based on the value of the <c>sys_alloc</c> carrier size
(<seealso marker="#Muycs">ycs</seealso>) parameter. The size of
@@ -143,9 +156,8 @@
<p>Coalescing of free blocks are always performed immediately.
Boundary tags (headers and footers) in free blocks are used
which makes the time complexity for coalescing constant.</p>
- <p> <marker id="strategy"></marker>
-
- The memory allocation strategy used for multiblock carriers by an
+ <p><marker id="strategy"></marker>The memory allocation strategy
+ used for multiblock carriers by an
allocator is configurable via the <seealso marker="#M_as">as</seealso>
parameter. Currently the following strategies are available:</p>
<taglist>
@@ -166,6 +178,14 @@
used. The time complexity is proportional to log N, where
N is the number of free blocks.</p>
</item>
+ <tag>Address order first fit</tag>
+ <item>
+ <p>Strategy: Find the block with the lowest address that satisfies the
+ requested block size.</p>
+ <p>Implementation: A balanced binary search tree is
+ used. The time complexity is proportional to log N, where
+ N is the number of free blocks.</p>
+ </item>
<tag>Good fit</tag>
<item>
<p>Strategy: Try to find the best fit, but settle for the best fit
@@ -194,6 +214,11 @@
</taglist>
</section>
+ <note><p>
+ Currently only allocators using the best fit and the address order
+ best fit strategies are able to use "small block multi block carriers".
+ </p></note>
+
<section>
<marker id="flags"></marker>
<title>System Flags Effecting erts_alloc</title>
@@ -215,6 +240,7 @@
the currently present allocators:</p>
<list type="bulleted">
<item><c>B: binary_alloc</c></item>
+ <item><c>C: sbmbc_alloc</c></item>
<item><c>D: std_alloc</c></item>
<item><c>E: ets_alloc</c></item>
<item><c>F: fix_alloc</c></item>
@@ -300,11 +326,11 @@
subsystem identifier, only the specific allocator identified will be
effected:</p>
<taglist>
- <tag><marker id="M_as"><c><![CDATA[+M<S>as bf|aobf|gf|af]]></c></marker></tag>
+ <tag><marker id="M_as"><c><![CDATA[+M<S>as bf|aobf|aoff|gf|af]]></c></marker></tag>
<item>
Allocation strategy. Valid strategies are <c>bf</c> (best fit),
- <c>aobf</c> (address order best fit), <c>gf</c> (good fit),
- and <c>af</c> (a fit). See
+ <c>aobf</c> (address order best fit), <c>aoff</c> (address order first fit),
+ <c>gf</c> (good fit), and <c>af</c> (a fit). See
<seealso marker="#strategy">the description of allocation strategies</seealso> in "the <c>alloc_util</c> framework" section.</item>
<tag><marker id="M_asbcst"><c><![CDATA[+M<S>asbcst <size>]]></c></marker></tag>
<item>
@@ -395,6 +421,20 @@
threshold will be placed in singleblock carriers. Blocks
smaller than this threshold will be placed in multiblock
carriers.</item>
+ <tag><marker id="M_sbmbcs"><c><![CDATA[+M<S>sbmbcs <size>]]></c></marker></tag>
+ <item>
+ Small block multiblock carrier size (in bytes). Memory blocks smaller
+ than the small block multiblock carrier threshold
+ (<seealso marker="#M_sbmbct">sbmbct</seealso>) will be placed in
+ multiblock carriers used for small blocks only. This parameter
+ determines the size of such carriers.
+ </item>
+ <tag><marker id="M_sbmbct"><c><![CDATA[+M<S>sbmbct <size>]]></c></marker></tag>
+ <item>
+ Small block multiblock carrier threshold (in bytes). Memory blocks
+ smaller than this threshold will be placed in multiblock carriers
+ used for small blocks only.
+ </item>
<tag><marker id="M_smbcs"><c><![CDATA[+M<S>smbcs <size>]]></c></marker></tag>
<item>
Smallest (<c>mseg_alloc</c>) multiblock carrier size (in
@@ -403,10 +443,10 @@
in "the <c>alloc_util</c> framework" section.</item>
<tag><marker id="M_t"><c><![CDATA[+M<S>t true|false|<amount>]]></c></marker></tag>
<item>
- Multiple, thread specific instances of the allocator.
- This option will only have any effect on the runtime system
- with SMP support. Default behaviour on the runtime system with
- SMP support (<c>N</c> equals the number of scheduler threads):
+ <p>Multiple, thread specific instances of the allocator.
+ This option will only have any effect on the runtime system
+ with SMP support. Default behaviour on the runtime system with
+ SMP support (<c>N</c> equals the number of scheduler threads):</p>
<taglist>
<tag><c>temp_alloc</c></tag>
<item><c>N + 1</c> instances.</item>
@@ -417,10 +457,10 @@
<c>16</c>. <c>16</c> instances when <c>N</c> is greater than
<c>16</c>.</item>
</taglist>
- <c>temp_alloc</c> will always use <c>N + 1</c> instances when
- this option has been enabled regardless of the amount passed.
- Other allocators will use the same amount of instances as the
- amount passed as long as it isn't greater than <c>N</c>.
+ <p><c>temp_alloc</c> will always use <c>N + 1</c> instances when
+ this option has been enabled regardless of the amount passed.
+ Other allocators will use the same amount of instances as the
+ amount passed as long as it isn't greater than <c>N</c>.</p>
</item>
</taglist>
<p>Currently the following flags are available for configuration of
diff --git a/erts/doc/src/escript.xml b/erts/doc/src/escript.xml
index a89449df23..66e904f64f 100644
--- a/erts/doc/src/escript.xml
+++ b/erts/doc/src/escript.xml
@@ -4,7 +4,7 @@
<comref>
<header>
<copyright>
- <year>2007</year><year>2010</year>
+ <year>2007</year><year>2011</year>
<holder>Ericsson AB. All Rights Reserved.</holder>
</copyright>
<legalnotice>
@@ -31,7 +31,7 @@
<com>escript</com>
<comsummary>Erlang scripting support</comsummary>
<description>
- <p><c><![CDATA[escript]]></c> provides support for running short Erlang programs
+ <p><c>escript</c> provides support for running short Erlang programs
without having to compile them first and an easy way to retrieve the
command line arguments.</p>
</description>
@@ -41,10 +41,10 @@
<name>escript escript-flags script-name script-arg1 script-arg2...</name>
<fsummary>Run a script written in Erlang</fsummary>
<desc>
- <p><c><![CDATA[escript]]></c> runs a script written in Erlang.</p>
+ <p><c>escript</c> runs a script written in Erlang.</p>
<p>Here follows an example.</p>
<pre>
-$ <input>cat factorial</input>
+$ <input>cat factorial</input>
#!/usr/bin/env escript
%% -*- erlang -*-
%%! -smp enable -sname factorial -mnesia debug verbose
@@ -59,11 +59,11 @@ main([String]) ->
end;
main(_) ->
usage().
-
+
usage() ->
io:format("usage: factorial integer\n"),
halt(1).
-
+
fac(0) -> 1;
fac(N) -> N * fac(N-1).
$ <input>factorial 5</input>
@@ -74,9 +74,8 @@ $ <input>factorial five</input>
usage: factorial integer </pre>
<p>The header of the Erlang script in the example differs from
a normal Erlang module. The first line is intended to be the
- interpreter line, which invokes
- <c><![CDATA[escript]]></c>. However if you invoke the
- <c><![CDATA[escript]]></c> like this</p>
+ interpreter line, which invokes <c>escript</c>. However if you
+ invoke the <c>escript</c> like this</p>
<pre>
$ <input>escript factorial 5</input> </pre>
<p>the contents of the first line does not matter, but it
@@ -93,13 +92,13 @@ $ <input>escript factorial 5</input> </pre>
%%! -smp enable -sname factorial -mnesia debug verbose</pre>
<p>Such an argument line must start with <c>%%!</c> and the
rest of the line will interpreted as arguments to the emulator.</p>
- <p>If you know the location of the <c><![CDATA[escript]]></c> executable, the first
- line can directly give the path to <c><![CDATA[escript]]></c>. For instance:</p>
+ <p>If you know the location of the <c>escript</c> executable, the first
+ line can directly give the path to <c>escript</c>. For instance:</p>
<pre>
#!/usr/local/bin/escript </pre>
<p>As any other kind of scripts, Erlang scripts will not work on
Unix platforms if the execution bit for the script file is not set.
- (Use <c><![CDATA[chmod +x script-name]]></c> to turn on the execution bit.)
+ (Use <c>chmod +x script-name</c> to turn on the execution bit.)
</p>
<p>The rest of the Erlang script file may either contain
@@ -108,33 +107,33 @@ $ <input>escript factorial 5</input> </pre>
<p>An Erlang script file must always contain the function
<em>main/1</em>. When the script is run, the
- <c><![CDATA[main/1]]></c> function will be called with a list
+ <c>main/1</c> function will be called with a list
of strings representing the arguments given to the script (not
changed or interpreted in any way).</p>
- <p>If the <c><![CDATA[main/1]]></c> function in the script returns successfully,
+ <p>If the <c>main/1</c> function in the script returns successfully,
the exit status for the script will be 0. If an exception is generated
during execution, a short message will be printed and the script terminated
with exit status 127.</p>
- <p>To return your own non-zero exit code, call <c><![CDATA[halt(ExitCode)]]></c>;
+ <p>To return your own non-zero exit code, call <c>halt(ExitCode)</c>;
for instance:</p>
<pre>
halt(1).</pre>
- <p>Call <c><![CDATA[escript:script_name/0]]></c> from your to
- script to retrieve the pathname of the script (the pathname
- is usually, but not always, absolute).</p>
+ <p>Call <seealso marker="#script_name_0">escript:script_name()</seealso>
+ from your to script to retrieve the pathname of the script
+ (the pathname is usually, but not always, absolute).</p>
<p>If the file contains source code (as in the example above),
it will be processed by the preprocessor <c>epp</c>. This
means that you for example may use pre-defined macros (such as
- <c><![CDATA[?MODULE]]></c>) as well as include directives like
- the <c><![CDATA[-include_lib]]></c> directive. For instance, use</p>
+ <c>?MODULE</c>) as well as include directives like
+ the <c>-include_lib</c> directive. For instance, use</p>
<pre>
--include_lib("kernel/include/file.hrl"). </pre>
+-include_lib("kernel/include/file.hrl").</pre>
<p>to include the record definitions for the records used by the
- <c><![CDATA[file:read_link_info/1]]></c> function.</p>
+ <c>file:read_link_info/1</c> function.</p>
<p>The script will be checked for syntactic and semantic
correctness before being run. If there are warnings (such as
@@ -144,7 +143,7 @@ halt(1).</pre>
127.</p>
<p>Both the module declaration and the export declaration of
- the <c><![CDATA[main/1]]></c> function are optional.</p>
+ the <c>main/1</c> function are optional.</p>
<p>By default, the script will be interpreted. You can force
it to be compiled by including the following line somewhere
@@ -154,7 +153,10 @@ halt(1).</pre>
<p>Execution of interpreted code is slower than compiled code.
If much of the execution takes place in interpreted code it
may be worthwhile to compile it, even though the compilation
- itself will take a little while.</p>
+ itself will take a little while. It is also possible to supply
+ <c>native</c> instead of compile, this will compile the script
+ using the native flag, again depending on the characteristics
+ of the escript this could or could not be worth while.</p>
<p>As mentioned earlier, it is possible to have a script which
contains precompiled <c>beam</c> code. In a precompiled
@@ -198,6 +200,180 @@ factorial 5 = 120
</pre>
</desc>
</func>
+ <func>
+ <name>escript:create(FileOrBin, Sections) -> ok | {ok, binary()} | {error, term()}</name>
+ <fsummary>Create an escript</fsummary>
+ <type>
+ <v>FileOrBin = filename() | 'binary'</v>
+ <v>Sections = [Header] Body | Body</v>
+ <v>Header = shebang | {shebang, Shebang}
+ | comment | {comment, Comment}
+ | {emu_args, EmuArgs}</v>
+ <v>Shebang = string() | 'default' | 'undefined'</v>
+ <v>Comment = string() | 'default' | 'undefined'</v>
+ <v>EmuArgs = string() | 'undefined'</v>
+ <v>Body = {source, SourceCode}
+ | {beam, BeamCode}
+ | {archive, ZipArchive}</v>
+ <v>SourceCode = BeamCode = ZipArchive = binary()</v>
+ </type>
+ <desc>
+ <p>The <marker id="create_2"></marker> <c>create/2</c>
+ function creates an escript from a list of sections. The
+ sections can be given in any order. An escript begins with an
+ optional <c>Header</c> followed by a mandatory <c>Body</c>. If
+ the header is present, it does always begin with a
+ <c>shebang</c>, possibly followed by a <c>comment</c> and
+ <c>emu_args</c>. The <c>shebang</c> defaults to
+ <c>"/usr/bin/env escript"</c>. The comment defaults to
+ <c>"This is an -*- erlang -*- file"</c>. The created escript
+ can either be returned as a binary or written to file.</p>
+
+ <p>As an example of how the function can be used, we create an
+ interpreted escript which uses emu_args to set some emulator
+ flag. In this case it happens to disable the smp_support. We
+ do also extract the different sections from the newly created
+ script:</p>
+ <pre>
+&gt; <input>Source = "%% Demo\nmain(_Args) ->\n io:format(erlang:system_info(smp_support)).\n".</input>
+"%% Demo\nmain(_Args) ->\n io:format(erlang:system_info(smp_support)).\n"
+&gt; <input>io:format("~s\n", [Source]).</input>
+%% Demo
+main(_Args) ->
+ io:format(erlang:system_info(smp_support)).
+
+ok
+&gt; <input>{ok, Bin} = escript:create(binary, [shebang, comment, {emu_args, "-smp disable"},
+ {source, list_to_binary(Source)}]).</input>
+{ok,&lt;&lt;"#!/usr/bin/env escript\n%% This is an -*- erlang -*- file\n%%!-smp disabl"...&gt;&gt;}
+&gt; <input>file:write_file("demo.escript", Bin).</input>
+ok
+&gt; <input>os:cmd("escript demo.escript").</input>
+"false"
+&gt; <input>escript:extract("demo.escript", []).</input>
+{ok,[{shebang,default}, {comment,default}, {emu_args,"-smp disable"},
+ {source,&lt;&lt;"%% Demo\nmain(_Args) ->\n io:format(erlang:system_info(smp_su"...&gt;&gt;}]}
+ </pre>
+
+ <p>An escript without header can be created like this:</p>
+<pre>
+&gt; <input>file:write_file("demo.erl",
+ ["%% demo.erl\n-module(demo).\n-export([main/1]).\n\n", Source]).</input>
+ok
+&gt; <input>{ok, _, BeamCode} = compile:file("demo.erl", [binary, debug_info]).</input>
+{ok,demo,
+ &lt;&lt;70,79,82,49,0,0,2,208,66,69,65,77,65,116,111,109,0,0,0,
+ 79,0,0,0,9,4,100,...&gt;&gt;}
+&gt; <input>escript:create("demo.beam", [{beam, BeamCode}]).</input>
+ok
+&gt; <input>escript:extract("demo.beam", []).</input>
+{ok,[{shebang,undefined}, {comment,undefined}, {emu_args,undefined},
+ {beam,&lt;&lt;70,79,82,49,0,0,3,68,66,69,65,77,65,116,
+ 111,109,0,0,0,83,0,0,0,9,...&gt;&gt;}]}
+&gt; <input>os:cmd("escript demo.beam").</input>
+"true"
+</pre>
+ <p>Here we create an archive script containing both Erlang
+ code as well as beam code. Then we iterate over all files in
+ the archive and collect their contents and some info about
+ them.
+ </p>
+<pre>
+&gt; <input>{ok, SourceCode} = file:read_file("demo.erl").</input>
+{ok,&lt;&lt;"%% demo.erl\n-module(demo).\n-export([main/1]).\n\n%% Demo\nmain(_Arg"...&gt;&gt;}
+&gt; <input>escript:create("demo.escript",
+ [shebang,
+ {archive, [{"demo.erl", SourceCode},
+ {"demo.beam", BeamCode}], []}]).</input>
+ok
+&gt; <input>{ok, [{shebang,default}, {comment,undefined}, {emu_args,undefined},
+ {archive, ArchiveBin}]} = escript:extract("demo.escript", []).</input>
+{ok,[{shebang,default}, {comment,undefined}, {emu_args,undefined},
+ {{archive,&lt;&lt;80,75,3,4,20,0,0,0,8,0,118,7,98,60,105,
+ 152,61,93,107,0,0,0,118,0,...&gt;&gt;}]}
+&gt; <input>file:write_file("demo.zip", ArchiveBin).</input>
+ok
+&gt; <input>zip:foldl(fun(N, I, B, A) -> [{N, I(), B()} | A] end, [], "demo.zip").</input>
+{ok,[{"demo.beam",
+ {file_info,748,regular,read_write,
+ {{2010,3,2},{0,59,22}},
+ {{2010,3,2},{0,59,22}},
+ {{2010,3,2},{0,59,22}},
+ 54,1,0,0,0,0,0},
+ &lt;&lt;70,79,82,49,0,0,2,228,66,69,65,77,65,116,111,109,0,0,0,
+ 83,0,0,...&gt;&gt;},
+ {"demo.erl",
+ {file_info,118,regular,read_write,
+ {{2010,3,2},{0,59,22}},
+ {{2010,3,2},{0,59,22}},
+ {{2010,3,2},{0,59,22}},
+ 54,1,0,0,0,0,0},
+ &lt;&lt;"%% demo.erl\n-module(demo).\n-export([main/1]).\n\n%% Demo\nmain(_Arg"...&gt;&gt;}]}</pre>
+ </desc>
+ </func>
+ <func>
+ <name>escript:extract(File, Options) -> {ok, Sections} | {error, term()}</name>
+ <fsummary>Parses an escript and extracts its sections</fsummary>
+ <type>
+ <v>File = filename()</v>
+ <v>Options = [] | [compile_source]</v>
+ <v>Sections = Headers Body</v>
+ <v>Headers = {shebang, Shebang}
+ {comment, Comment}
+ {emu_args, EmuArgs}</v>
+ <v>Shebang = string() | 'default' | 'undefined'</v>
+ <v>Comment = string() | 'default' | 'undefined'</v>
+ <v>EmuArgs = string() | 'undefined'</v>
+ <v>Body = {source, SourceCode}
+ | {source, BeamCode}
+ | {beam, BeamCode}
+ | {archive, ZipArchive}</v>
+ <v>SourceCode = BeamCode = ZipArchive = binary()</v>
+ </type>
+ <desc>
+ <p>The <marker id="extract_2"></marker> <c>extract/2</c>
+ function parses an escript and extracts its sections. This is
+ the reverse of <c>create/2</c>.</p>
+
+ <p>All sections are returned even if they do not exist in the
+ escript. If a particular section happens to have the same
+ value as the default value, the extracted value is set to the
+ atom <c>default</c>. If a section is missing, the extracted
+ value is set to the atom <c>undefined</c>. </p>
+
+ <p>The <c>compile_source</c> option only affects the result if
+ the escript contains <c>source</c> code. In that case the
+ Erlang code is automatically compiled and <c>{source,
+ BeamCode}</c> is returned instead of <c>{source,
+ SourceCode}</c>.</p>
+
+ <pre>
+&gt; <input>escript:create("demo.escript",
+ [shebang, {archive, [{"demo.erl", SourceCode},
+ {"demo.beam", BeamCode}], []}]).</input>
+ok
+&gt; <input>{ok, [{shebang,default}, {comment,undefined}, {emu_args,undefined},
+ {archive, ArchiveBin}]} =
+ escript:extract("demo.escript", []).</input>
+{ok,[{{archive,&lt;&lt;80,75,3,4,20,0,0,0,8,0,118,7,98,60,105,
+ 152,61,93,107,0,0,0,118,0,...&gt;&gt;}
+ {emu_args,undefined}]}
+ </pre>
+ </desc>
+ </func>
+ <func>
+ <name>escript:script_name() -> File</name>
+ <fsummary>Returns the name of an escript</fsummary>
+ <type>
+ <v>File = filename()</v>
+ </type>
+ <desc>
+ <p>The <marker id="script_name_0"></marker>
+ <c>script_name/0</c> function returns the name of the escript
+ being executed. If the function is invoked outside the context
+ of an escript, the behavior is undefined.</p>
+ </desc>
+ </func>
</funcs>
<section>
@@ -224,6 +400,9 @@ factorial 5 = 120
Warnings and errors (if any) are written to the standard output, but
the script will not be run. The exit status will be 0 if there were
no errors, and 127 otherwise.</item>
+
+ <tag>-n</tag>
+ <item>Compile the escript using the +native flag.</item>
</taglist>
</section>
</comref>
diff --git a/erts/doc/src/init.xml b/erts/doc/src/init.xml
index 33364c709a..d5c43f6e57 100644
--- a/erts/doc/src/init.xml
+++ b/erts/doc/src/init.xml
@@ -4,7 +4,7 @@
<erlref>
<header>
<copyright>
- <year>1996</year><year>2009</year>
+ <year>1996</year><year>2011</year>
<holder>Ericsson AB. All Rights Reserved.</holder>
</copyright>
<legalnotice>
@@ -47,15 +47,12 @@
</description>
<funcs>
<func>
- <name>boot(BootArgs) -> void()</name>
+ <name name="boot" arity="1"/>
<fsummary>Start the Erlang runtime system</fsummary>
- <type>
- <v>BootArgs = [binary()]</v>
- </type>
<desc>
<p>Starts the Erlang runtime system. This function is called
when the emulator is started and coordinates system start-up.</p>
- <p><c>BootArgs</c> are all command line arguments except
+ <p><c><anno>BootArgs</anno></c> are all command line arguments except
the emulator flags, that is, flags and plain arguments. See
<seealso marker="erts:erl">erl(1)</seealso>.</p>
<p><c>init</c> itself interprets some of the flags, see
@@ -67,30 +64,12 @@
</desc>
</func>
<func>
- <name>get_args() -> [Arg]</name>
- <fsummary>Get all non-flag command line arguments</fsummary>
- <type>
- <v>Arg = atom()</v>
- </type>
- <desc>
- <p>Returns any plain command line arguments as a list of atoms
- (possibly empty). It is recommended that
- <c>get_plain_arguments/1</c> is used instead, because of
- the limited length of atoms.</p>
- </desc>
- </func>
- <func>
- <name>get_argument(Flag) -> {ok, Arg} | error</name>
+ <name name="get_argument" arity="1"/>
<fsummary>Get the values associated with a command line user flag</fsummary>
- <type>
- <v>Flag = atom()</v>
- <v>Arg = [Values]</v>
- <v>&nbsp;Values = [string()]</v>
- </type>
<desc>
<p>Returns all values associated with the command line user flag
- <c>Flag</c>. If <c>Flag</c> is provided several times, each
- <c>Values</c> is returned in preserved order.</p>
+ <c><anno>Flag</anno></c>. If <c><anno>Flag</anno></c> is provided several times, each
+ <c><anno>Values</anno></c> is returned in preserved order.</p>
<pre>
% <input>erl -a b c -a d</input>
...
@@ -126,48 +105,37 @@
</desc>
</func>
<func>
- <name>get_arguments() -> Flags</name>
+ <name name="get_arguments" arity="0"/>
<fsummary>Get all command line user flags</fsummary>
- <type>
- <v>Flags = [{Flag, Values}]</v>
- <v>&nbsp;Flag = atom()</v>
- <v>&nbsp;Values = [string()]</v>
- </type>
<desc>
<p>Returns all command line flags, as well as the system
defined flags, see <c>get_argument/1</c>.</p>
</desc>
</func>
<func>
- <name>get_plain_arguments() -> [Arg]</name>
+ <name name="get_plain_arguments" arity="0"/>
<fsummary>Get all non-flag command line arguments</fsummary>
- <type>
- <v>Arg = string()</v>
- </type>
<desc>
<p>Returns any plain command line arguments as a list of strings
(possibly empty).</p>
</desc>
</func>
<func>
- <name>get_status() -> {InternalStatus, ProvidedStatus}</name>
+ <name name="get_status" arity="0"/>
<fsummary>Get system status information</fsummary>
- <type>
- <v>InternalStatus = starting | started | stopping</v>
- <v>ProvidedStatus = term()</v>
- </type>
+ <type name="internal_status"/>
<desc>
<p>The current status of the <c>init</c> process can be
inspected. During system startup (initialization),
- <c>InternalStatus</c> is <c>starting</c>, and
- <c>ProvidedStatus</c> indicates how far the boot script has
+ <c><anno>InternalStatus</anno></c> is <c>starting</c>, and
+ <c><anno>ProvidedStatus</anno></c> indicates how far the boot script has
been interpreted. Each <c>{progress, Info}</c> term
- interpreted in the boot script affects <c>ProvidedStatus</c>,
- that is, <c>ProvidedStatus</c> gets the value of <c>Info</c>.</p>
+ interpreted in the boot script affects <c><anno>ProvidedStatus</anno></c>,
+ that is, <c><anno>ProvidedStatus</anno></c> gets the value of <c>Info</c>.</p>
</desc>
</func>
<func>
- <name>reboot() -> void()</name>
+ <name name="reboot" arity="0"/>
<fsummary>Take down and restart an Erlang node smoothly</fsummary>
<desc>
<p>All applications are taken down smoothly, all code is
@@ -181,7 +149,7 @@
</desc>
</func>
<func>
- <name>restart() -> void()</name>
+ <name name="restart" arity="0"/>
<fsummary>Restart the running Erlang node</fsummary>
<desc>
<p>The system is restarted <em>inside</em> the running Erlang
@@ -196,20 +164,17 @@
</desc>
</func>
<func>
- <name>script_id() -> Id</name>
+ <name name="script_id" arity="0"/>
<fsummary>Get the identity of the used boot script</fsummary>
- <type>
- <v>Id = term()</v>
- </type>
<desc>
<p>Get the identity of the boot script used to boot the system.
- <c>Id</c> can be any Erlang term. In the delivered boot
- scripts, <c>Id</c> is <c>{Name, Vsn}</c>. <c>Name</c> and
+ <c><anno>Id</anno></c> can be any Erlang term. In the delivered boot
+ scripts, <c><anno>Id</anno></c> is <c>{Name, Vsn}</c>. <c>Name</c> and
<c>Vsn</c> are strings.</p>
</desc>
</func>
<func>
- <name>stop() -> void()</name>
+ <name name="stop" arity="0"/>
<fsummary>Take down an Erlang node smoothly</fsummary>
<desc>
<p>All applications are taken down smoothly, all code is
@@ -223,15 +188,12 @@
</desc>
</func>
<func>
- <name>stop(Status) -> void()</name>
+ <name name="stop" arity="1"/>
<fsummary>Take down an Erlang node smoothly</fsummary>
- <type>
- <v>Status = int()>=0 | string()</v>
- </type>
<desc>
<p>All applications are taken down smoothly, all code is
unloaded, and all ports are closed before the system
- terminates by calling <c>halt(Status)</c>. If the
+ terminates by calling <c>halt(<anno>Status</anno>)</c>. If the
<c>-heart</c> command line flag was given, the <c>heart</c>
program is terminated before the Erlang node
terminates. Refer to <c>heart(3)</c> for more
diff --git a/erts/doc/src/match_spec.xml b/erts/doc/src/match_spec.xml
index b9f955e4db..f0390c9db8 100644
--- a/erts/doc/src/match_spec.xml
+++ b/erts/doc/src/match_spec.xml
@@ -60,7 +60,7 @@
<section>
<title>Grammar</title>
- <p>A match_spec can be described in this <em>informal</em> grammar:</p>
+ <p>A match_spec used in tracing can be described in this <em>informal</em> grammar:</p>
<list type="bulleted">
<item>MatchExpression ::= [ MatchFunction, ... ]
</item>
@@ -117,6 +117,52 @@
<c><![CDATA[display]]></c> | <c><![CDATA[caller]]></c> | <c><![CDATA[set_tcw]]></c> |
<c><![CDATA[silent]]></c></item>
</list>
+
+ <p>A match_spec used in ets can be described in this <em>informal</em> grammar:</p>
+ <list type="bulleted">
+ <item>MatchExpression ::= [ MatchFunction, ... ]
+ </item>
+ <item>MatchFunction ::= { MatchHead, MatchConditions, MatchBody }
+ </item>
+ <item>MatchHead ::= MatchVariable | <c><![CDATA['_']]></c> | { MatchHeadPart, ... }
+ </item>
+ <item>MatchHeadPart ::= term() | MatchVariable | <c><![CDATA['_']]></c></item>
+ <item>MatchVariable ::= '$&lt;number&gt;'
+ </item>
+ <item>MatchConditions ::= [ MatchCondition, ...] | <c><![CDATA[[]]]></c></item>
+ <item>MatchCondition ::= { GuardFunction } |
+ { GuardFunction, ConditionExpression, ... }
+ </item>
+ <item>BoolFunction ::= <c><![CDATA[is_atom]]></c> | <c><![CDATA[is_constant]]></c> |
+ <c><![CDATA[is_float]]></c> | <c><![CDATA[is_integer]]></c> | <c><![CDATA[is_list]]></c> |
+ <c><![CDATA[is_number]]></c> | <c><![CDATA[is_pid]]></c> | <c><![CDATA[is_port]]></c> |
+ <c><![CDATA[is_reference]]></c> | <c><![CDATA[is_tuple]]></c> | <c><![CDATA[is_binary]]></c> |
+ <c><![CDATA[is_function]]></c> | <c><![CDATA[is_record]]></c> | <c><![CDATA[is_seq_trace]]></c> |
+ <c><![CDATA['and']]></c> | <c><![CDATA['or']]></c> | <c><![CDATA['not']]></c> | <c><![CDATA['xor']]></c> |
+ <c><![CDATA[andalso]]></c> | <c><![CDATA[orelse]]></c></item>
+ <item>ConditionExpression ::= ExprMatchVariable | { GuardFunction } |
+ { GuardFunction, ConditionExpression, ... } | TermConstruct
+ </item>
+ <item>ExprMatchVariable ::= MatchVariable (bound in the MatchHead) |
+ <c><![CDATA['$_']]></c> | <c><![CDATA['$$']]></c></item>
+ <item>TermConstruct = {{}} | {{ ConditionExpression, ... }} |
+ <c><![CDATA[[]]]></c> | [ConditionExpression, ...] | NonCompositeTerm | Constant
+ </item>
+ <item>NonCompositeTerm ::= term() (not list or tuple)
+ </item>
+ <item>Constant ::= {<c><![CDATA[const]]></c>, term()}
+ </item>
+ <item>GuardFunction ::= BoolFunction | <c><![CDATA[abs]]></c> |
+ <c><![CDATA[element]]></c> | <c><![CDATA[hd]]></c> | <c><![CDATA[length]]></c> | <c><![CDATA[node]]></c> |
+ <c><![CDATA[round]]></c> | <c><![CDATA[size]]></c> | <c><![CDATA[tl]]></c> | <c><![CDATA[trunc]]></c> |
+ <c><![CDATA['+']]></c> | <c><![CDATA['-']]></c> | <c><![CDATA['*']]></c> | <c><![CDATA['div']]></c> |
+ <c><![CDATA['rem']]></c> | <c><![CDATA['band']]></c> | <c><![CDATA['bor']]></c> | <c><![CDATA['bxor']]></c> |
+ <c><![CDATA['bnot']]></c> | <c><![CDATA['bsl']]></c> | <c><![CDATA['bsr']]></c> | <c><![CDATA['>']]></c> |
+ <c><![CDATA['>=']]></c> | <c><![CDATA['<']]></c> | <c><![CDATA['=<']]></c> | <c><![CDATA['=:=']]></c> |
+ <c><![CDATA['==']]></c> | <c><![CDATA['=/=']]></c> | <c><![CDATA['/=']]></c> | <c><![CDATA[self]]></c> |
+ <c><![CDATA[get_tcw]]></c></item>
+ <item>MatchBody ::= [ ConditionExpression, ... ]</item>
+ </list>
</section>
<section>
@@ -453,8 +499,8 @@
<section>
<title>Differences between match specifications in ETS and tracing</title>
<p>ETS match specifications are there to produce a return
- value. Usually the expression contains one single
- <c><![CDATA[ActionTerm]]></c> which defines the return value without having
+ value. Usually the <c><![CDATA[MatchBody]]></c> contains one single
+ <c><![CDATA[ConditionExpression]]></c> which defines the return value without having
any side effects. Calls with side effects are not allowed in the
ETS context.</p>
<p>When tracing there is no return value to produce, the
@@ -530,7 +576,7 @@
the atom 'strider' and the tuple arity is 3 and return the whole
object.</p>
<code type="none"><![CDATA[
-[{{strider,'_'.'_'},
+[{{strider,'_','_'},
[],
['$_']}]
]]></code>
diff --git a/erts/doc/src/notes.xml b/erts/doc/src/notes.xml
index 09950e865b..4cef9669dd 100644
--- a/erts/doc/src/notes.xml
+++ b/erts/doc/src/notes.xml
@@ -4,7 +4,7 @@
<chapter>
<header>
<copyright>
- <year>2004</year><year>2010</year>
+ <year>2004</year><year>2011</year>
<holder>Ericsson AB. All Rights Reserved.</holder>
</copyright>
<legalnotice>
@@ -30,6 +30,2263 @@
</header>
<p>This document describes the changes made to the ERTS application.</p>
+<section><title>Erts 5.8.5</title>
+
+ <section><title>Fixed Bugs and Malfunctions</title>
+ <list>
+ <item>
+ <p>
+ Several bugs concerning constant binary constructions
+ such as &lt;&lt;0:4294967295&gt;&gt; have been corrected.
+ Depending on the actual size of the binary and the type
+ of run-time system (32-bit, halfword, 64-bit), such
+ expression could either crash the run-time system or make
+ the loader refuse loading of the module.</p>
+ <p>
+ Own Id: OTP-9284</p>
+ </item>
+ <item>
+ <p>
+ The Erlsrv utility failed to stop the erlang machine if
+ no StopAction was defined when the service was stopped.
+ This is now corrected.</p>
+ <p>
+ Own Id: OTP-9344</p>
+ </item>
+ <item>
+ <p>
+ Due to a bug in glibc the runtime system could abort
+ while trying to destroy a mutex. A fix for this was
+ introduced in R14B02. This fix did, however, not solve
+ the problem. The runtime system will now issue a warning
+ instead of aborting.</p>
+ <p>
+ Own Id: OTP-9373 Aux Id: OTP-9009 </p>
+ </item>
+ <item>
+ <p>
+ Replace atom in DRV macro in prim_file with string</p>
+ <p>
+ An experimental version of Dialyzer discovered that the
+ atom that replaced the DRV macro in prim_file ends up in
+ calls to erlang:open_port({spawn, Driver}, Portopts) as
+ the Driver argument. The documentation states that this
+ call requires a string there.</p>
+ <p>
+ This change is also consistent with the one introduced in
+ commit 0f03b1e9d2bef3bc830c31a369261af4c5234727 by Kostis
+ Sagonas.</p>
+ <p>
+ Own Id: OTP-9377</p>
+ </item>
+ <item>
+ <p>
+ Fix typos in the epmd documentation (Thanks to Holger
+ Wei� )</p>
+ <p>
+ Own Id: OTP-9387</p>
+ </item>
+ <item>
+ <p>
+ Fix faulty integer terms created by NIF API from 64-bit
+ integers on halfword emulator. (Thanks to Paolo Negri and
+ Paul Davis)</p>
+ <p>
+ Own Id: OTP-9394</p>
+ </item>
+ <item>
+ <p>
+ Fix <c>epmd</c> crash on vxworks caused by faulty
+ argument to select() system call.</p>
+ <p>
+ Own Id: OTP-9427 Aux Id: seq11855 </p>
+ </item>
+ <item>
+ <p>
+ The ets:test_ms function could in rare cases truncate the
+ error messages. This is now corrected.</p>
+ <p>
+ Own Id: OTP-9435</p>
+ </item>
+ <item>
+ <p>
+ Fix bug related to hibernate and HiPE (clear
+ F_HIBERNATE_SCHED flag)</p>
+ <p>
+ F_HIBERNATE_SCHED flag that was introduced in
+ b7ecdcd1ae9e11b8f75e must be cleared in hipe_mode_switch
+ as well. Otherwise, processes running HiPE code that
+ hibernate, wake up and then trap into a BIF will not be
+ rescheduled.(Thanks to Paul Guyot)</p>
+ <p>
+ Own Id: OTP-9452</p>
+ </item>
+ <item>
+ <p>
+ Fix bug in FreeBSD topology detection code (Thanks to
+ Paul Guyot)</p>
+ <p>
+ Own Id: OTP-9453</p>
+ </item>
+ <item>
+ <p>
+ Fix use of logical operator &amp;&amp; with constant
+ operand instead of bitwise &amp; (Thanks to Cristian
+ Greco)</p>
+ <p>
+ Own Id: OTP-9454</p>
+ </item>
+ <item>
+ <p>
+ inet: error if fd does not match socket domain</p>
+ <p>
+ If an IPv4 fd is opened as an IPv6 socket, unexpected
+ behaviour can occur. For example, if an IPv4 UDP socket
+ is opened and passed into Erlang as an IPv6 socket, the
+ first 3 bytes (corresponding to 1 byte representing the
+ protocol family, 2 bytes set to the port) are stripped
+ from the payload. The cause of the UDP payload truncation
+ happens in inet_drv.c:packet_inet_input when a call to
+ inet_get_address fails silently because the family is set
+ to PF_INET6 but the buffer len is the size of an IPv4
+ struct sockaddr_in.</p>
+ <p>
+ (Thanks to Andrew Tunnell-Jones for finding the bug and
+ the test case!)</p>
+ <p>
+ Own Id: OTP-9455</p>
+ </item>
+ <item>
+ <p>
+ erts: use a union to avoid strict aliasing issues</p>
+ <p>
+ Use a union for pointer type conversion to avoid compiler
+ warnings about strict-aliasing violations with gcc-4.1.
+ gcc >= 4.2 does not emit the warning. erts: adapt
+ matrix_nif to R14 erl_nif API changes (Thanks To Tuncer
+ Ayaz)</p>
+ <p>
+ Own Id: OTP-9487</p>
+ </item>
+ <item>
+ <p>
+ fix 64-bit issues in the garbage collection (Thanks to
+ Richard Carlsson)</p>
+ <p>
+ Own Id: OTP-9488</p>
+ </item>
+ <item>
+ <p>
+ epmd: fix compiler warnings</p>
+ <p>
+ Suppress compiler warnings about ignored return values.
+ (Thanks to Michael Santos )</p>
+ <p>
+ Own Id: OTP-9500</p>
+ </item>
+ <item>
+ <p>
+ Fix non-existing function (erlang:disconnect/1) in
+ distributed reference manual (Thanks to Fabian Kr�l)</p>
+ <p>
+ Own Id: OTP-9504</p>
+ </item>
+ <item>
+ <p>
+ Document fdatasync -lrt requirement (SunOS &lt;= 5.10)
+ (Thanks to Tuncer Ayaz)</p>
+ <p>
+ Own Id: OTP-9512</p>
+ </item>
+ <item>
+ <p>
+ Let epmd ignore empty ERL_EPMD_ADDRESS</p>
+ <p>
+ If the environment variable ERL_EPMD_ADDRESS is set to
+ the empty string, empd now behaves like it does by
+ default when ERL_EPMD_ADDRESS is unset. That is, in this
+ case, epmd now listens on all available interfaces
+ instead of using only the loopback interface, which
+ happened because epmd added the loopback address to the
+ (in this case empty) list of addresses specified via
+ ERL_EPMD_ADDRESS.</p>
+ <p>
+ Also, epmd now ignores ERL_EPMD_ADDRESS if it contains
+ only separator characters (comma and space).</p>
+ <p>
+ The same applies to epmd's -address option.(Thanks to
+ Holger Wei�)</p>
+ <p>
+ Own Id: OTP-9525</p>
+ </item>
+ <item>
+ <p>
+ Remove dead code in erl_compile (Thanks to Tuncer Ayaz)</p>
+ <p>
+ Own Id: OTP-9527</p>
+ </item>
+ <item>
+ <p>
+ Add erlang:external_size/2 BIF</p>
+ <p>
+ This BIF's second parameter is a list of options.
+ Currently the only allowed option is {minor_version,
+ Version} where version is either 0 (default) or 1.
+ (Thanks to Filipe David Manana )</p>
+ <p>
+ Own Id: OTP-9528</p>
+ </item>
+ <item>
+ <p>
+ Fix enif_compare on 64bits machines</p>
+ <p>
+ In 64bits machines the Sint type has a size of 8 bytes,
+ while on 32bits machines it has a 4 bytes size.
+ enif_compare was ignoring this and therefore returning
+ incorrect values when the result of the CMP function
+ (which returns a Sint value) doesn't fit in 4 bytes.
+ (Thanks to Filipe David Manana)</p>
+ <p>
+ Own Id: OTP-9533</p>
+ </item>
+ <item>
+ <p>
+ Implement or fix -Werror option</p>
+ <p>
+ If -Werror is enabled and there are warnings no output
+ file is written. Also make sure that error/warning
+ reporting is consistent. (Thanks to Tuncer Ayaz)</p>
+ <p>
+ Own Id: OTP-9536</p>
+ </item>
+ <item>
+ <p>In some rare cases we did not have a run queue when
+ scheduling misc ops. This is now fixed.</p>
+ <p>
+ Own Id: OTP-9537</p>
+ </item>
+ <item>
+ <p>Remove misc. compiler warnings</p>
+ <p>
+ Own Id: OTP-9542</p>
+ </item>
+ <item>
+ <p>
+ Two bugs in gen_sctp has been corrected: getopts/setopts
+ hence also send could only be called from socket owner,
+ and options 'linger', 'rcvbuf' and 'sndbuf' was read from
+ wrong protocol layer hence read wrong values by getopts.</p>
+ <p>
+ Own Id: OTP-9544</p>
+ </item>
+ <item>
+ <p>
+ Erlang/OTP can now be built on MacOS X Lion.</p>
+ <p>
+ Own Id: OTP-9547</p>
+ </item>
+ <item>
+ <p> XML files have been corrected. </p>
+ <p>
+ Own Id: OTP-9550 Aux Id: OTP-9541 </p>
+ </item>
+ <item>
+ <p>
+ Fix potential errors inspired by running cppcheck(1)
+ (Thanks to Christian von Roques)</p>
+ <p>
+ Own Id: OTP-9557</p>
+ </item>
+ <item>
+ <p>When auxiliary work was enqueued on a scheduler, the
+ wakeup of the scheduler in order to handle this work
+ could be lost. Wakeups in order to handle ordinary work
+ were not effected by this bug. The bug only effected
+ runtime systems with SMP support as follows:</p> <list>
+ <item>Deallocation of some ETS data structures could be
+ delayed.</item> <item>On Linux systems not using the NPTL
+ thread library (typically ancient systems with kernel
+ versions prior to 2.6) and Windows systems, the <c>{Port,
+ {exit_status, Status}}</c> message from a terminating
+ port program could be delayed. That is, it only effected
+ port programs which had been started by passing
+ <c>exit_status</c> as an option to
+ <c>open_port/2</c>.</item> </list>
+ <p>
+ Own Id: OTP-9567</p>
+ </item>
+ <item>
+ <p>
+ Handle rare race in the crypto key server functionality</p>
+ <p>
+ Own Id: OTP-9586</p>
+ </item>
+ </list>
+ </section>
+
+
+ <section><title>Improvements and New Features</title>
+ <list>
+ <item>
+ <p> Types and specifications have been added. </p>
+ <p>
+ Own Id: OTP-9356</p>
+ </item>
+ <item>
+ <p>
+ New allocator strategy "address order first fit". May
+ ease the emptying of memory carriers and thereby real
+ release of memory back to the OS.</p>
+ <p>
+ Own Id: OTP-9424</p>
+ </item>
+ <item>
+ <p>
+ The new <c>erlang:check_old_code/1</c> BIF checks whether
+ a module has old code.</p>
+ <p>
+ Own Id: OTP-9495</p>
+ </item>
+ <item>
+ <p> Update documentation and specifications of some of
+ the zlib functions. </p>
+ <p>
+ Own Id: OTP-9506</p>
+ </item>
+ <item>
+ <p>
+ Detect the available CPUs on IRIX</p>
+ <p>
+ Add support for querying the number of configured and
+ online processors on SGI systems running IRIX.(Thanks to
+ Holger Wei�)</p>
+ <p>
+ Own Id: OTP-9531</p>
+ </item>
+ </list>
+ </section>
+
+</section>
+
+<section><title>Erts 5.8.4</title>
+
+ <section><title>Fixed Bugs and Malfunctions</title>
+ <list>
+ <item>
+ <p>Fix binary and iolist overflow problems. Typically
+ problems arose in length calculation where the result
+ would exceed (1 bsl 32 - 1).</p>
+ <p>
+ Own Id: OTP-9118</p>
+ </item>
+ <item>
+ <p>
+ Using the old erlang shell (i.e. erl instead on werl) on
+ windows and doing several init:restart's would eventually
+ hang the VM. That is no longer the case.</p>
+ <p>
+ Own Id: OTP-9139</p>
+ </item>
+ <item>
+ <p>
+ Removed recursive C code when printing Erlang terms to
+ buffers, avoiding stack overflows that could cause VM to
+ crash.</p>
+ <p>
+ Own Id: OTP-9140</p>
+ </item>
+ <item>
+ <p>
+ The send_timeout option in gen_tcp did not work properly
+ in active mode or with {active,once} options. This is now
+ corrected.</p>
+ <p>
+ Own Id: OTP-9145</p>
+ </item>
+ <item>
+ <p>
+ Fixed various typos across the documentation (Thanks to
+ Tuncer Ayaz)</p>
+ <p>
+ Own Id: OTP-9154</p>
+ </item>
+ <item>
+ <p>Remove duplicate stack entries which could occur after
+ calling certain BIFs.</p>
+ <p>
+ Own Id: OTP-9163</p>
+ </item>
+ <item>
+ <p>
+ A race when starting two nodes simultaneously using
+ run_erl has been removed.</p>
+ <p>
+ Own Id: OTP-9164</p>
+ </item>
+ <item>
+ <p>
+ Add documentation on .erlang processing back again
+ (Thanks to Gabor Liptak)</p>
+ <p>
+ Own Id: OTP-9189</p>
+ </item>
+ <item>
+ <p>
+ Remove gratuitous paren in driver_entry(Thanks to Tuncer
+ Ayaz)</p>
+ <p>
+ Own Id: OTP-9192</p>
+ </item>
+ <item>
+ <p>
+ Fix some wrong pointer dereferences (Thanks to Cristian
+ Greco)</p>
+ <p>
+ Own Id: OTP-9194</p>
+ </item>
+ <item>
+ <p>
+ erts: Remove unused variables (Thanks to Tuncer Ayaz)</p>
+ <p>
+ Own Id: OTP-9205</p>
+ </item>
+ <item>
+ <p>
+ The documentation for <c>init:get_args/0</c> has been
+ removed. <c>init:get_args/0</c> itself was deprecated in
+ R9C and removed in R12B. (Thanks to Eric Pailleau.)</p>
+ <p>
+ Own Id: OTP-9209</p>
+ </item>
+ <item>
+ <p>
+ Allow user to specify the IP address epmd binds to</p>
+ <p>
+ The IP address(es) epmd binds to can now be specified by
+ the user, either via epmd's new "-address" option or (if
+ that's not used) by setting the environment variable
+ ERL_EPMD_ADDRESS. Multiple addresses may be specified
+ using a comma-separated list. If the loopback address is
+ not in this list, it will be added implicitly, so that
+ the daemon can be queried by an interactive epmd
+ process.(Thanks to Holger Wei�)</p>
+ <p>
+ Own Id: OTP-9213</p>
+ </item>
+ <item>
+ <p>
+ epmd: include host address in local access check</p>
+ <p>
+ In FreeBSD jails, the source and destination address of
+ connections to localhost are changed to be the IP address
+ of the jail. Consider connections from the host's IP
+ address to itself (e.g., the source and destination
+ address match) to be local for the access control checks.
+ (Thanks to Michal Santos and Tom at diogunix.com)</p>
+ <p>
+ Own Id: OTP-9214</p>
+ </item>
+ <item>
+ <p>
+ Fix list returned by net_kernel:epmd_module</p>
+ <p>
+ Function epmd_module of net_kernel returns a list instead
+ of an atom, when the epmd_module-flag is used. (Thanks to
+ Markus Knofe)</p>
+ <p>
+ Own Id: OTP-9215</p>
+ </item>
+ <item>
+ <p>
+ Fix epmd's dbg_perror() output</p>
+ <p>
+ The dbg_perror() function now hands the current errno
+ value over to dbg_gen_printf(). This fixes the problem
+ that errno had been reset to zero by the time it was used
+ (to print the corresponding error message) in the
+ dbg_gen_printf() function. (Thanks to Holger Wei�)</p>
+ <p>
+ Own Id: OTP-9223</p>
+ </item>
+ <item>
+ <p>
+ heart: remove garbage appended to heart command</p>
+ <p>
+ heart:get_cmd/0 is documented to return an empty string
+ if the command is cleared. get_cmd/0 returns 2 extra
+ bytes: 1 byte for the trailing null, 1 byte from the op
+ (the op is an unsigned char and 2 bytes are allocated for
+ it in the returned buffer). (Thanks to Michael Santos)</p>
+ <p>
+ Own Id: OTP-9224</p>
+ </item>
+ <item>
+ <p>
+ file: fix hang reading compressed files</p>
+ <p>
+ The gzio driver goes into an infinite loop when reading
+ past the end of a compressed file. Reported-By: Alex
+ Morarash (Thanks to Michael Santos)</p>
+ <p>
+ Own Id: OTP-9245</p>
+ </item>
+ <item>
+ <p>Eliminate alias warnings from gcc 4.5.2</p>
+ <p>
+ Own Id: OTP-9250</p>
+ </item>
+ <item>
+ <p>
+ Unsigned integer may overflow in error message (Thanks to
+ Michael Santos)</p>
+ <p>
+ Own Id: OTP-9251</p>
+ </item>
+ <item>
+ <p>
+ Driver names should be strings, not atoms</p>
+ <p>
+ Own Id: OTP-9253</p>
+ </item>
+ <item>
+ <p>
+ driver_entry: Remove gratuitous paren and fix typo
+ (Thanks to Tuncer Ayaz)</p>
+ <p>
+ Own Id: OTP-9254</p>
+ </item>
+ <item>
+ <p>
+ Fix format specifiers in erl_exit messages</p>
+ <p>
+ Fix an error message by using an unsigned integer
+ specifier as seen in a tweet by @metabrew: #erlang VM
+ crashed with "no next heap size found: -2090496108,
+ offset 0", suddenly allocated all available RAM</p>
+ <p>
+ Also correct mis-typed string formats in bif.c.(Thanks to
+ Michael Santos)</p>
+ <p>
+ Own Id: OTP-9262</p>
+ </item>
+ <item>
+ <p>
+ net_drv: remove unused tcp request id inet_drv: remove
+ gratuitous assignment (Thanks to Tuncer Ayaz)</p>
+ <p>
+ Own Id: OTP-9263</p>
+ </item>
+ <item>
+ <p>
+ Teach run_erl RUN_ERL_DISABLE_FLOWCNTRL for disabling
+ flow control</p>
+ <p>
+ Flow control can cause unwanted behaviour of the beam
+ process, if accidentally hit Ctrl-S (instead of Ctrl-D to
+ detach) the entire beam may be blocked.</p>
+ <p>
+ Fix this problem by making it possible to turn off flow
+ control by setting the environment variable
+ RUN_ERL_DISABLE_FLOWCNTRL. (Thanks to Jonas Faklkevik)</p>
+ <p>
+ Own Id: OTP-9270</p>
+ </item>
+ <item>
+ <p>The following bugs due to missing memory barriers have
+ been fixed:</p> <list> <item><p> ETS tables using the
+ <c>write_concurrency</c> option could potentially get
+ into an internally inconsistent state. </p></item>
+ <item><p> ETS tables using the <c>ordered_set</c> option
+ could potentially get into an internally inconsistent
+ state. </p></item> <item><p> A number of memory barriers
+ have been added when building with the
+ <c>libatomic_ops</c> API (i.e. when passing
+ <c>--with-libatomic_ops=PATH</c> to <c>configure</c>) and
+ the tilera atomics API (i.e. when building for the tilera
+ chip). Note that these bugs were due to erroneous usage
+ of the APIs, and not in the implementations of the APIs.
+ When using these APIs the following bugs where
+ present:</p> <list> <item><p> The BIF
+ <c>erlang:ports/0</c> could return an erroneous result.
+ </p></item> <item><p> A thread blocking other threads
+ during code loading, or setup of tracing could
+ potentially read invalid data. </p></item> <item><p>
+ Fixation of ETS tables could potentially get into an
+ internally inconsistent state. </p></item> </list>
+ </item> </list>
+ <p>
+ Own Id: OTP-9281</p>
+ </item>
+ <item>
+ <p>
+ Fix halfword bug for ETS ordered_set when doing
+ <c>select/match</c> with partly bound key.</p>
+ <p>
+ Own Id: OTP-9292</p>
+ </item>
+ <item>
+ <p>
+ Fix bug in <c>code:is_module_native</c> that caused crash
+ for deleted modules.</p>
+ <p>
+ Own Id: OTP-9298</p>
+ </item>
+ <item>
+ <p>
+ Calling <c>driver_async_cancel()</c> could cause a
+ scheduler thread to enter an eternal loop doing no useful
+ work. (Thanks to Anders Ramsell)</p>
+ <p>
+ Own Id: OTP-9302</p>
+ </item>
+ </list>
+ </section>
+
+
+ <section><title>Improvements and New Features</title>
+ <list>
+ <item>
+ <p>
+ New <c>enif_is_exception function</c> to allow NIFs to
+ determine whether an <c>ERL_NIF_TERM</c> represents an
+ exception. (Thanks to Steve Vinoski)</p>
+ <p>
+ Own Id: OTP-9150</p>
+ </item>
+ <item>
+ <p>
+ A process being garbage collected by another process
+ could be scheduled on another scheduler. This prevented
+ this scheduler from doing any useful work until the
+ garbage collection was done. This either occurred due to
+ a explicit call to the <c>garbage_collect/1</c> BIF, or
+ due to a garbage collection part of code loading. A
+ process being garbage collected like this will now not be
+ scheduled until the garbage collection has completed.</p>
+ <p>
+ Own Id: OTP-9211</p>
+ </item>
+ <item>
+ <p>
+ Remove unnecessary validation copy in
+ prim_file:drv_command/3 (Thanks to Tony Rogvall)</p>
+ <p>
+ Own Id: OTP-9276</p>
+ </item>
+ <item>
+ <p>
+ Symbolic link handling on windows have been slightly
+ updated to map error conditions more consequently and
+ correctly read directory links created outside of the
+ Erlang environment.</p>
+ <p>
+ Own Id: OTP-9279</p>
+ </item>
+ <item>
+ <p>
+ Due to standard library DLL mismatches between versions
+ of OpenSSL and Erlang/OTP, OpenSSL is now linked
+ statically to the crypto driver on Windows. This fixes
+ problems starting crypto when running Erlang as a service
+ on all Windows versions.</p>
+ <p>
+ Own Id: OTP-9280</p>
+ </item>
+ <item>
+ <p>Halfword emulator memory handling improvements:</p>
+ <list> <item><p>Much more of internal memory structures
+ have been made able to use "high" memory and are no
+ longer restricted to the 4Gb limit that still applies for
+ all process heap data.</p> </item> <item><p>Fixed faulty
+ values from <c>erlang:memory()</c> caused by 32-bit
+ counter overflow.</p> </item> <item><p>New counter
+ <c>low</c> in <c>erlang:memory()</c> that sums up all
+ memory restricted by 4Gb limit.</p> </item> </list>
+ <p>
+ Own Id: OTP-9291 Aux Id: seq11841 </p>
+ </item>
+ <item>
+ <p>
+ The value set in the undocumented and unsupported
+ ERL_version_FLAGS (e.g. ERL_R14B03_FLAGS) environment
+ variable can now be overridden by the command line
+ (similar to ERL_AFLAGS).</p>
+ <p>
+ Own Id: OTP-9297</p>
+ </item>
+ </list>
+ </section>
+
+</section>
+
+<section><title>Erts 5.8.3.2</title>
+
+ <section><title>Known Bugs and Problems</title>
+ <list>
+ <item>
+ <p>
+ Fix halfword emulator bug in <c>ets:select_delete</c> for
+ <c>ordered_set</c> that caused emulator to crash.</p>
+ <p>
+ Own Id: OTP-9258 Aux Id: seq11836 </p>
+ </item>
+ </list>
+ </section>
+
+</section>
+
+<section><title>Erts 5.8.3.1</title>
+
+ <section><title>Fixed Bugs and Malfunctions</title>
+ <list>
+ <item>
+ <p>
+ Ets table type ordered_set could order large integer keys
+ wrongly on pure 64bit platforms. This is now corrected.</p>
+ <p>
+ Own Id: OTP-9181</p>
+ </item>
+ <item>
+ <p>
+ The status of a process was unnecessarily set to waiting
+ before a process was enqueued in a run queue. This bug
+ was harmless up until OTP-R14B01. In OTP-R14B02
+ <c>erlang:hibernate/3</c> was fixed (OTP-9125). After the
+ introduction of OTP-9125, the previously harmless process
+ status bug sometimes caused erroneous badarg exceptions
+ from <c>process_info()</c>.</p>
+ <p>
+ OTP-9125 also introduced a thread unsafe access to the
+ status field of a process which now also have been fixed.</p>
+ <p>
+ *** INCOMPATIBILITY with noxs ***</p>
+ <p>
+ Own Id: OTP-9197</p>
+ </item>
+ </list>
+ </section>
+
+</section>
+
+<section><title>Erts 5.8.3</title>
+
+ <section><title>Fixed Bugs and Malfunctions</title>
+ <list>
+ <item>
+ <p>
+ The scroll wheel now scrolls the werl window on Windows.</p>
+ <p>
+ Own Id: OTP-8985</p>
+ </item>
+ <item>
+ <p>
+ Some malformed distribution messages could cause VM to
+ crash, this is now corrected.</p>
+ <p>
+ Own Id: OTP-8993</p>
+ </item>
+ <item>
+ <p>
+ The OS function getifaddrs() can return NULL in some
+ address fields for e.g PPP and tunnel devices which
+ caused the emulator to segfault. This bug has now been
+ corrected.</p>
+ <p>
+ Own Id: OTP-8996</p>
+ </item>
+ <item>
+ <p>
+ The expression &lt;&lt;A:0&gt;&gt; would always produce
+ an empty binary, even if <c>A</c> was not an integer.
+ Corrected to cause a <c>badarg</c> exception if the type
+ of <c>A</c> is invalid. (Thanks to Zvi.)</p>
+ <p>
+ Own Id: OTP-8997</p>
+ </item>
+ <item>
+ <p>
+ A bug that potentially could cause an emulator crash when
+ deleting an ETS-table has been fixed. A resource leak
+ when hitting the maximum amount of ETS-tables allowed has
+ also been fixed.</p>
+ <p>
+ Own Id: OTP-8999</p>
+ </item>
+ <item>
+ <p>
+ A bug in the <c>exit/2</c> BIF could potentially cause an
+ emulator crash.</p>
+ <p>
+ Own Id: OTP-9005</p>
+ </item>
+ <item>
+ <p>
+ Due to a bug in glibc the runtime system could abort
+ while trying to destroy a mutex. The runtime system will
+ now issue a warning instead of aborting.</p>
+ <p>
+ Own Id: OTP-9009</p>
+ </item>
+ <item>
+ <p>
+ A bug in epmd could create strange behaviour when
+ listen() calls failed. This is now corrected thanks to
+ Steve Vinoski.</p>
+ <p>
+ Own Id: OTP-9024</p>
+ </item>
+ <item>
+ <p>When setting file_info the win32_driver will now
+ correctly set access and modified time. Previously these
+ entities were swapped.</p>
+ <p>
+ Own Id: OTP-9046</p>
+ </item>
+ <item>
+ <p>
+ Setting scheduler bind type to <c>unbound</c> failed if
+ binding of schedulers wasn't supported, or if CPU
+ topology wasn't present. This even though the
+ documentation stated that it is possible to set the bind
+ type to <c>unbound</c>.</p>
+ <p>
+ Own Id: OTP-9056 Aux Id: Seq11779 </p>
+ </item>
+ <item>
+ <p>Two problems were fixed in crash dump: The time left
+ for timers are now shown as unsigned integers and the
+ contents of ordered_set ETS tables is no longer
+ included.</p>
+ <p>
+ Own Id: OTP-9057</p>
+ </item>
+ <item>
+ <p>
+ The VM could fail to set IP_TOS and SO_PRIORITY in
+ certain situations, either because sockets were supplied
+ as open file descriptors, or because SO_PRIORITY by
+ default was set higher than the user can explicitly set
+ it to. Those situations are now handled.</p>
+ <p>
+ Own Id: OTP-9069</p>
+ </item>
+ <item>
+ <p>
+ Wx on MacOS X generated complains on stderr about certain
+ cocoa functions not beeing called from the "Main thread".
+ This is now corrected.</p>
+ <p>
+ Own Id: OTP-9081</p>
+ </item>
+ <item>
+ <p>
+ Fix a couple typos in driver_entry(3) (thanks to Tuncer
+ Ayaz).</p>
+ <p>
+ Own Id: OTP-9085</p>
+ </item>
+ <item>
+ <p>
+ Mention that "-detached" implies "-noinput"</p>
+ <p>
+ Clarify that specifying "-noinput" is unnecessary if the
+ "-detached" flag is given. (thanks to Holger Wei�)</p>
+ <p>
+ Own Id: OTP-9086</p>
+ </item>
+ <item>
+ <p>
+ A potential problem (found by code inspection) when
+ calling a fun whose code was not loaded has been fixed.</p>
+ <p>
+ Own Id: OTP-9095</p>
+ </item>
+ <item>
+ <p>
+ The emulator could get into a state where it didn't check
+ for I/O.</p>
+ <p>
+ Own Id: OTP-9105 Aux Id: Seq11798 </p>
+ </item>
+ <item>
+ <p>
+ Attempting to create binaries exceeding 2Gb (using for
+ example <c>term_to_binary/1</c>) would crash the emulator
+ with an attempt to allocate huge amounts of memory.
+ (Thanks to Jon Meredith.)</p>
+ <p>
+ Own Id: OTP-9117</p>
+ </item>
+ <item>
+ <p>
+ Fix erlang:hibernate/3 on HiPE enabled emulator (Thanks
+ to Paul Guyot)</p>
+ <p>
+ Own Id: OTP-9125</p>
+ </item>
+ </list>
+ </section>
+
+
+ <section><title>Improvements and New Features</title>
+ <list>
+ <item>
+ <p>From this release, the previously experimental
+ halfword emulator is now official. It can be enabled by
+ giving the <c>--enable-halfword-emulator</c> option to
+ the <c>configure</c> script.</p>
+ <p>The halfword emulator is a 64-bit application, but
+ uses halfwords (32-bit words) for all data in Erlang
+ processes, therefore using less memory and being faster
+ than the standard 64-bit emulator. The total size of all
+ BEAM code and all process data for all processes is
+ limited to 4Gb, but ETS tables and off-heap binaries are
+ only limited by the amount of available memory.</p>
+ <p>
+ Own Id: OTP-8941</p>
+ </item>
+ <item>
+ <p>
+ 32-bit atomic memory operations have been introduced
+ internally in the run time system, and are now used where
+ appropriate. There were previously only atomic memory
+ operations of word size available. The 32-bit atomic
+ memory operations slightly reduce memory consumption, and
+ slightly improve performance on 64-bit runtime systems.</p>
+ <p>
+ Own Id: OTP-8974</p>
+ </item>
+ <item>
+ <p>
+ Performance enhancements for looking up timer-entries and
+ removing timers from the wheel.</p>
+ <p>
+ Own Id: OTP-8990</p>
+ </item>
+ <item>
+ <p>
+ Write accesses to ETS tables have been optimized by
+ reducing the amount of atomic memory operations needed
+ during a write access.</p>
+ <p>
+ Own Id: OTP-9000</p>
+ </item>
+ <item>
+ <p>
+ Strange C coding in the VM made the -D_FORTIFY_SOURCE
+ option to gcc-4.5 react badly. The code is now cleaned up
+ so that it's accepted by gcc-4.5.</p>
+ <p>
+ Own Id: OTP-9025</p>
+ </item>
+ <item>
+ <p>
+ The memory footprint for loaded code has been somewhat
+ reduced (especially in the 64-bit BEAM machine).</p>
+ <p>
+ Own Id: OTP-9030</p>
+ </item>
+ <item>
+ <p>
+ The maximum number of allowed arguments for an Erlang
+ function has been lowered from 256 to 255, so that the
+ number of arguments can now fit in a byte.</p>
+ <p>
+ Own Id: OTP-9049</p>
+ </item>
+ <item>
+ <p>
+ Dependency generation for Makefiles has been added to the
+ compiler and erlc. See the manual pages for
+ <c>compile</c> and <c>erlc</c>. (Thanks to Jean-Sebastien
+ Pedron.)</p>
+ <p>
+ Own Id: OTP-9065</p>
+ </item>
+ </list>
+ </section>
+
+</section>
+
+<section><title>Erts 5.8.2</title>
+
+ <section><title>Fixed Bugs and Malfunctions</title>
+ <list>
+ <item>
+ <p> Fix format_man_pages so it handles all man sections
+ and remove warnings/errors in various man pages. </p>
+ <p>
+ Own Id: OTP-8600</p>
+ </item>
+ <item>
+ <p>
+ The <c>configure</c> command line argument <seealso
+ marker="doc/installation_guide:INSTALL#How-to-Build-and-Install-ErlangOTP_A-Closer-Look-at-the-individual-Steps_Configuring">--enable-ethread-pre-pentium4-compatibility</seealso>
+ had no effect. This option is now also automatically
+ enabled if required on the build machine.</p>
+ <p>
+ Own Id: OTP-8847</p>
+ </item>
+ <item>
+ <p>
+ Windows 2003 and Windows XP pre SP3 would sometimes not
+ start the Erlang R14B VM at all due to a bug in the cpu
+ topology detection. The bug affects Windows only, no
+ other platform is even remotely affected. The bug is now
+ corrected.</p>
+ <p>
+ Own Id: OTP-8876</p>
+ </item>
+ <item>
+ <p>
+ The HiPE run-time in the 64-bit emulator could do a
+ 64-bit write to a 32-bit struct field. It happened to be
+ harmless on Intel/AMD processors. Corrected. (Thanks to
+ Mikael Pettersson.)</p>
+ <p>
+ Own Id: OTP-8877</p>
+ </item>
+ <item>
+ <p>
+ A bug in <seealso
+ marker="erl_driver#erl_drv_tsd_get">erl_drv_tsd_get()</seealso>
+ and <seealso
+ marker="erl_nif#enif_tsd_get">enif_tsd_get()</seealso>
+ could cause an emulator crash. These functions are
+ currently not used in OTP. That is, the crash only occur
+ on systems with user implemented NIF libraries, or
+ drivers that use one of these functions.</p>
+ <p>
+ Own Id: OTP-8889</p>
+ </item>
+ <item>
+ <p>
+ Calling <c>erlang:system_info({cpu_topology,
+ CpuTopologyType})</c> with another <c>CpuTopologyType</c>
+ element than one of the documented atoms <c>defined</c>,
+ <c>detected</c>, or <c>used</c> caused an emulator crash.
+ (Thanks to Paul Guyot)</p>
+ <p>
+ Own Id: OTP-8914</p>
+ </item>
+ <item>
+ <p>
+ The ERTS internal rwlock implementation could get into an
+ inconsistent state. This bug was very seldom triggered,
+ but could be during heavy contention. The bug was
+ introduced in R14B (erts-5.8.1).</p>
+ <p>
+ The bug was most likely to be triggered when using the
+ <c>read_concurrency</c> option on an ETS table that was
+ frequently accessed from multiple processes doing lots of
+ writes and reads. That is, in a situation where you
+ typically don't want to use the <c>read_concurrency</c>
+ option in the first place.</p>
+ <p>
+ Own Id: OTP-8925 Aux Id: OTP-8544 </p>
+ </item>
+ <item>
+ <p>
+ Tracing to port could cause an emulator crash when
+ unloading the trace driver.</p>
+ <p>
+ Own Id: OTP-8932</p>
+ </item>
+ <item>
+ <p>
+ Removed use of CancelIoEx on Windows that had been shown
+ to cause problems with some drivers.</p>
+ <p>
+ Own Id: OTP-8937</p>
+ </item>
+ <item>
+ <p>
+ The fallback implementation used when no native atomic
+ implementation was found did not compile. (Thanks to
+ Patrick Baggett, and Tuncer Ayaz)</p>
+ <p>
+ Own Id: OTP-8944</p>
+ </item>
+ <item>
+ <p>
+ Some integer values used during load balancing could
+ under rare circumstances wrap causing a load unbalance
+ between schedulers.</p>
+ <p>
+ Own Id: OTP-8950</p>
+ </item>
+ <item>
+ <p>
+ The windows VM now correctly handles appending to large
+ files (> 4GB).</p>
+ <p>
+ Own Id: OTP-8958</p>
+ </item>
+ <item>
+ <p>
+ Name resolving of IPv6 addresses has been implemented for
+ Windows versions that support it. The use of ancient
+ resolver flags (AI_V4MAPPED | AI_ADDRCONFIG) to the
+ getaddrinfo() function has been removed since e.g FreeBSD
+ regard mapped IPv4 addresses to be a security problem and
+ the semantics of the address configured flag is
+ uncertain.</p>
+ <p>
+ Own Id: OTP-8969</p>
+ </item>
+ </list>
+ </section>
+
+
+ <section><title>Improvements and New Features</title>
+ <list>
+ <item>
+ <p>
+ The help texts produced by the <c>configure</c> scripts
+ in the top directory and in the erts directory have been
+ aligned and cleaned up.</p>
+ <p>
+ Own Id: OTP-8859</p>
+ </item>
+ <item>
+ <p>
+ When the runtime system had fewer schedulers than logical
+ processors, the system could get an unnecessarily large
+ amount reader groups.</p>
+ <p>
+ Own Id: OTP-8861</p>
+ </item>
+ <item>
+ <p>
+ <c>run_rel</c> has been updated to support Solaris's
+ /dev/ptmx device and to load the necessary STREAMS
+ modules so that <c>to_erl</c> can provide terminal echo
+ of keyboard input. (Thanks to Ryan Tilder.)</p>
+ <p>
+ Own Id: OTP-8878</p>
+ </item>
+ <item>
+ <p>
+ The Erlang VM now supports Unicode filenames. The feature
+ is turned on by default on systems where Unicode
+ filenames are mandatory (Windows and MacOSX), but can be
+ enabled on other systems with the '+fnu' emulator option.
+ Enabling the Unicode filename feature on systems where it
+ is not default is however considered experimental and not
+ to be used for production. Together with the Unicode file
+ name support, the concept of "raw filenames" is
+ introduced, which means filenames provided without
+ implicit unicode encoding translation. Raw filenames are
+ provided as binaries, not lists. For further information,
+ see stdlib users guide and the chapter about using
+ Unicode in Erlang. Also see the file module manual page.</p>
+ <p>
+ *** POTENTIAL INCOMPATIBILITY ***</p>
+ <p>
+ Own Id: OTP-8887</p>
+ </item>
+ <item>
+ <p>Buffer overflows have been prevented in <c>erlc</c>,
+ <c>dialyzer</c>, <c>typer</c>, <c>run_test</c>,
+ <c>heart</c>, <c>escript</c>, and <c>erlexec</c>.</p>
+ (Thanks to Michael Santos.)
+ <p>
+ Own Id: OTP-8892</p>
+ </item>
+ <item>
+ <p>
+ The runtime system is now less eager to suspend processes
+ sending messages over the distribution. The default value
+ of the distribution buffer busy limit has also been
+ increased from 128 KB to 1 MB. This in order to improve
+ throughput.</p>
+ <p>
+ Own Id: OTP-8901</p>
+ </item>
+ <item>
+ <p>
+ The distribution buffer busy limit can now be configured
+ at system startup. For more information see the
+ documentation of the <c>erl</c> <seealso
+ marker="erl#+zdbbl">+zdbbl</seealso> command line flag.
+ (Thanks to Scott Lystig Fritchie)</p>
+ <p>
+ Own Id: OTP-8912</p>
+ </item>
+ <item>
+ <p>
+ The inet driver internal buffer stack implementation has
+ been rewritten in order to reduce lock contention.</p>
+ <p>
+ Own Id: OTP-8916</p>
+ </item>
+ <item>
+ <p>
+ New ETS option <c>compressed</c>, to enable a more
+ compact storage format at the expence of heavier table
+ operations. For test and evaluation, <c>erl +ec</c> can
+ be used to force compression on all ETS tables.</p>
+ <p>
+ Own Id: OTP-8922 Aux Id: seq11658 </p>
+ </item>
+ <item>
+ <p>
+ There is now a new function inet:getifaddrs/0 modeled
+ after C library function getifaddrs() on BSD and LInux
+ that reports existing interfaces and their addresses on
+ the host. This replaces the undocumented and unsupported
+ inet:getiflist/0 and inet:ifget/2.</p>
+ <p>
+ Own Id: OTP-8926</p>
+ </item>
+ <item>
+ <p>
+ Support for detection of CPU topology and binding of
+ schedulers on FreeBSD 8 have been added. (Thanks to Paul
+ Guyot)</p>
+ <p>
+ Own Id: OTP-8939</p>
+ </item>
+ <item>
+ <p>
+ Several bugs related to hibernate/3 and HiPE have been
+ corrected. (Thanks to Paul Guyot.)</p>
+ <p>
+ Own Id: OTP-8952</p>
+ </item>
+ <item>
+ <p>
+ Support for soft and hard links on Windows versions and
+ filesystems that support them is added.</p>
+ <p>
+ Own Id: OTP-8955</p>
+ </item>
+ <item>
+ <p>
+ The win32 virtual machine is now linked large address
+ aware. his allows the Erlang VM to use up to 3 gigs of
+ address space on Windows instead of the default of 2
+ gigs.</p>
+ <p>
+ Own Id: OTP-8956</p>
+ </item>
+ </list>
+ </section>
+
+</section>
+
+<section><title>Erts 5.8.1.2</title>
+
+ <section><title>Fixed Bugs and Malfunctions</title>
+ <list>
+ <item>
+ <p> Fix that the documentation top index generator can
+ handle an Ericsson internal application group. </p>
+ <p>
+ Own Id: OTP-8875</p>
+ </item>
+ <item>
+ <p>In embedded mode, on_load handlers that called
+ <c>code:priv_dir/1</c> or other functions in <c>code</c>
+ would hang the system. Since the <c>crypto</c>
+ application now contains an on_loader handler that calls
+ <c>code:priv_dir/1</c>, including the <c>crypto</c>
+ application in the boot file would prevent the system
+ from starting.</p>
+ <p>Also extended the <c>-init_debug</c> option to print
+ information about on_load handlers being run to
+ facilitate debugging.</p>
+ <p>
+ Own Id: OTP-8902 Aux Id: seq11703 </p>
+ </item>
+ </list>
+ </section>
+
+</section>
+
+<section><title>Erts 5.8.1.1</title>
+
+ <section><title>Fixed Bugs and Malfunctions</title>
+ <list>
+ <item>
+ <p>
+ Windows 2003 and Windows XP pre SP3 would sometimes not
+ start the Erlang R14B VM at all due to a bug in the cpu
+ topology detection. The bug affects Windows only, no
+ other platform is even remotely affected. The bug is now
+ corrected.</p>
+ <p>
+ Own Id: OTP-8876</p>
+ </item>
+ </list>
+ </section>
+
+</section>
+
+<section><title>Erts 5.8.1</title>
+
+ <section><title>Fixed Bugs and Malfunctions</title>
+ <list>
+ <item>
+ <p>
+ Very small floating point numbers generated errors when
+ converting from list to float in some versions of the VM,
+ this is now corrected so that i.e.
+ list_to_float("1.0e-324"). returns 0.0 in all versions of
+ Erlang.</p>
+ <p>
+ Own Id: OTP-7178</p>
+ </item>
+ <item>
+ <p>
+ Windows Vista and Windows 7 file system virtualization,
+ which makes "old style" windows programs execute in a
+ file system sandbox, was previously unintentionally
+ turned on for the Erlang VM. This is now corrected so
+ that i.e. writes to C:\Program Files\. without
+ administrator privileges will fail.</p>
+ <p>
+ Own Id: OTP-7405</p>
+ </item>
+ <item>
+ <p>
+ Fix faulty 64-bit integer term output from drivers. Large
+ 64-bits integers did not generate correct bignums and
+ could even cause emulator crash. Only affects drivers
+ using ERL_DRV_INT64 or ERL_DRV_UINT64, introduced in
+ R13B03.</p>
+ <p>
+ Own Id: OTP-8716</p>
+ </item>
+ <item>
+ <p>
+ Fixed: inet:setopts(S, [{linger,{true,2}}]) returned
+ {error,einval} for SCTP sockets. The inet_drv had a bug
+ when checking the option size.</p>
+ <p>
+ Own Id: OTP-8726 Aux Id: seq11617 </p>
+ </item>
+ <item>
+ <p>Fix libm linking with --as-needed flag
+ <p>
+ When building with "--as-needed" linker flags on Linux
+ the build will fail. This has now been fixed.</p>
+ <p>
+ (Thanks to Christian Faulhammer)</p></p>
+ <p>
+ Own Id: OTP-8728</p>
+ </item>
+ <item>
+ <p>
+ gen_udp:connect/3 was broken for SCTP enabled builds. It
+ did not detect remote end errors as it should.</p>
+ <p>
+ Own Id: OTP-8729</p>
+ </item>
+ <item>
+ <p>Reduce the risk of integer wrapping in bin vheap size
+ counting.</p> <p>The vheap size series will now use the
+ golden ratio instead of doubling and fibonacci
+ sequences.</p>
+ <p>
+ Own Id: OTP-8730</p>
+ </item>
+ <item>
+ <p>
+ ETS ordered_set containing <c>[]</c> as key could cause
+ strange thing to happen, like an infinite hanging
+ <c>ets:select</c>.</p>
+ <p>
+ Own Id: OTP-8732</p>
+ </item>
+ <item>
+ <p>reference() has been substituted for ref() in the
+ documentation.</p>
+ <p>
+ Own Id: OTP-8733</p>
+ </item>
+ <item>
+ <p>
+ When a native compiled module called a not loaded
+ non-native compiled module that had an on_load function,
+ the export entries were trashed after code loading so on
+ the next call from the native compiled module to the
+ non-native compiled the emulator crashed. This bug has
+ now been fixed.</p>
+ <p>
+ Own Id: OTP-8736</p>
+ </item>
+ <item>
+ <p>
+ HiPE-enabled Erlang VMs running on BSD systems sometimes
+ generated messages like "Yikes! erts_alloc() returned
+ misaligned address 0x8016a512c". Fixed. (Thanks to Mikael
+ Pettersson.)</p>
+ <p>
+ Own Id: OTP-8769</p>
+ </item>
+ <item>
+ <p>
+ A race condition in <c>erts_poll()</c> could cause delay
+ of poll for I/O.</p>
+ <p>
+ Own Id: OTP-8773</p>
+ </item>
+ <item>
+ <p>
+ Removed some potential vulnerabilities from the Erlang
+ Port Mapper Daemon (epmd) and straightened up access
+ control. Also removed hazardous interfaces allowing
+ anyone on a machine to forcefully unregister other nodes.
+ This means that the ei_unregister/erl_unregister
+ interfaces in erl_interface is rendered not only error
+ prone and mystifying as before, but totally ineffective.
+ The old behaviour of unchecked node unregistering can be
+ restored if needed, see epmd documentation for details.</p>
+ <p>
+ *** POTENTIAL INCOMPATIBILITY ***</p>
+ <p>
+ Own Id: OTP-8780</p>
+ </item>
+ <item>
+ <p> Building in a source tree without prebuilt platform
+ independent build results failed on the SSL examples
+ when: </p> <list><item> cross building. This has been
+ solved by not building the SSL examples during a cross
+ build. </item><item> building on Windows. </item></list>
+ <p>
+ Own Id: OTP-8791</p>
+ </item>
+ <item>
+ <p>
+ inet:getsockopt for SCTP sctp_default_send_param had a
+ bug to not initialize required feilds causing random
+ answers. It is now corrected.</p>
+ <p>
+ Own Id: OTP-8795 Aux Id: seq11655 </p>
+ </item>
+ <item>
+ <p>
+ The hipe_bifs:get_hrvtime/0 BIF now always returns a real
+ value even if the "perfctr" Linux kernel extension is not
+ available. It used to return a dummy value. (Thanks to
+ Mikael Pettersson.)</p>
+ <p>
+ Own Id: OTP-8798</p>
+ </item>
+ <item>
+ <p>
+ Calling a native-code compiled module with an
+ <c>on_load</c> function could cause a crash. (Thanks to
+ Mikael Pettersson.)</p>
+ <p>
+ Own Id: OTP-8799</p>
+ </item>
+ <item>
+ <p>The emulator could crash while writing a crash dump if
+ native-compiled modules had been loaded. (Thanks to Paul
+ Guyot.)</p>
+ <p>
+ Own Id: OTP-8801</p>
+ </item>
+ <item>
+ <p>
+ The garbage collector could crash if invoked from
+ native-compiled code after a call to a BIF. (Thanks to
+ Paul Guyot.)</p>
+ <p>
+ Own Id: OTP-8821</p>
+ </item>
+ <item>
+ <p>
+ A rare memory leak in binary:matches is removed</p>
+ <p>
+ Own Id: OTP-8823</p>
+ </item>
+ <item>
+ <p>For a socket in the HTTP packet mode, the return value
+ from <c>gen_tcp:recv/2,3</c> if there is an error in the
+ header will be <c>{ok,{http_error,String}}</c> instead of
+ <c>{error,{http_error,String}}</c> to be consistent with
+ <c>ssl:recv/2,3</c>.</p>
+ <p>
+ *** POTENTIAL INCOMPATIBILITY ***</p>
+ <p>
+ Own Id: OTP-8831</p>
+ </item>
+ </list>
+ </section>
+
+
+ <section><title>Improvements and New Features</title>
+ <list>
+ <item>
+ <p>
+ ets:select_reverse/{1,2,3} are now documented.</p>
+ <p>
+ Own Id: OTP-7863</p>
+ </item>
+ <item>
+ <p>
+ External format of integers changed to make full use of
+ all 32 bits of INTEGER_EXT. This is a compatible change
+ as old code can read full 32-bit integers but only
+ produce 28-bit integers as INTEGER_EXT.</p>
+ <p>
+ Own Id: OTP-8540 Aux Id: seq11534 </p>
+ </item>
+ <item>
+ <p>
+ Large parts of the <c>ethread</c> library have been
+ rewritten. The <c>ethread</c> library is an Erlang
+ runtime system internal, portable thread library used by
+ the runtime system itself.</p>
+ <p>
+ Most notable improvement is a reader optimized rwlock
+ implementation which dramatically improve the performance
+ of read-lock/read-unlock operations on multi processor
+ systems by avoiding ping-ponging of the rwlock cache
+ lines. The reader optimized rwlock implementation is used
+ by miscellaneous rwlocks in the runtime system that are
+ known to be read-locked frequently, and can be enabled on
+ ETS tables by passing the <seealso
+ marker="stdlib:ets#new_2_read_concurrency">{read_concurrency,
+ true}</seealso> option upon table creation. See the
+ documentation of <seealso
+ marker="stdlib:ets#new/2">ets:new/2</seealso> for more
+ information. The reader optimized rwlock implementation
+ can be fine tuned when starting the runtime system. For
+ more information, see the documentation of the <seealso
+ marker="erts:erl#+rg">+rg</seealso> command line argument
+ of <c>erl</c>.</p>
+ <p>
+ There is also a new implementation of rwlocks that is not
+ optimized for readers. Both implementations interleaves
+ readers and writers during contention as opposed to,
+ e.g., the NPTL (Linux) pthread rwlock implementation
+ which use either a reader or writer preferred strategy.
+ The reader/writer preferred strategy is problematic since
+ it starves threads doing the non-preferred operation.</p>
+ <p>
+ The new rwlock implementations in general performs better
+ in ERTS than common pthread implementations. However, in
+ some extremely heavily contended cases this is not the
+ case. Such heavy contention can more or less only appear
+ on ETS tables. This when multiple processes do very large
+ amounts of write locked operations simultaneously on the
+ same table. Such use of ETS is bad regardless of rwlock
+ implementation, will never scale, and is something we
+ strongly advise against.</p>
+ <p>
+ The new rwlock implementations depend on atomic
+ operations. If no native atomic implementation is found,
+ a fallback solution will be used. Using the fallback
+ implies a performance degradation. That is, it is more
+ important now than before to build OTP with a native
+ atomic implementation.</p>
+ <p>
+ The <c>ethread</c> library contains native atomic
+ implementations for, x86 (32 and 64 bit), powerpc (32
+ bit), sparc V9 (32 and 64 bit), and tilera (32 bit). On
+ other hardware gcc's builtin support for atomic memory
+ access will be used if such exists. If no such support is
+ found, <c>configure</c> will warn about no atomic
+ implementation available.</p>
+ <p>
+ The <c>ethread</c> library can now also use the
+ <c>libatomic_ops</c> library for atomic memory accesses.
+ This makes it possible for the Erlang runtime system to
+ utilize optimized native atomic operations on more
+ platforms than before. If <c>configure</c> warns about no
+ atomic implementation available, try using the
+ <c>libatomic_ops</c> library. Use the <seealso
+ marker="doc/installation_guide:INSTALL#How-to-Build-and-Install-ErlangOTP_A-Closer-Look-at-the-individual-Steps_Configuring">--with-libatomic_ops=PATH</seealso>
+ <c>configure</c> command line argument when specifying
+ where the <c>libatomic_ops</c> installation is located.
+ The <c>libatomic_ops</c> library can be downloaded from:
+ <url
+ href="http://www.hpl.hp.com/research/linux/atomic_ops/">http://www.hpl.hp.com/research/linux/atomic_ops/</url></p>
+ <p>
+ The changed API of the <c>ethread</c> library has also
+ caused modifications in the Erlang runtime system.
+ Preparations for the to come "delayed deallocation"
+ feature has also been done since it depends on the
+ <c>ethread</c> library.</p>
+ <p>
+ <em>Note</em>: When building for x86, the <c>ethread</c>
+ library will now use instructions that first appeared on
+ the pentium 4 processor. If you want the runtime system
+ to be compatible with older processors (back to 486) you
+ need to pass the <seealso
+ marker="doc/installation_guide:INSTALL#How-to-Build-and-Install-ErlangOTP_A-Closer-Look-at-the-individual-Steps_Configuring">--enable-ethread-pre-pentium4-compatibility</seealso>
+ <c>configure</c> command line argument when configuring
+ the system.</p>
+ <p>
+ Own Id: OTP-8544</p>
+ </item>
+ <item>
+ <p>
+ erlang:localtime_to_universaltime({{2008, 8, 1}, {0, 0,
+ 0}},true) when TZ=UTC now behaves consistently on all
+ Unix platforms.</p>
+ <p>
+ The problem fixed was originally reported by Paul Guyot
+ on erlang-bugs mailing list:</p>
+ <p>
+ http://www.erlang.org/pipermail/erlang-bugs/2008-November/001077.html</p>
+ <p>
+ Own Id: OTP-8580</p>
+ </item>
+ <item>
+ <p>
+ Optimization reducing memory consumption by two words per
+ ETS object.</p>
+ <p>
+ Own Id: OTP-8737</p>
+ </item>
+ <item>
+ <p>
+ Fixes for unsupported halfword-emulator</p>
+ <p>
+ Own Id: OTP-8745</p>
+ </item>
+ <item>
+ <p>
+ NIF 64-bit integer support; <c>enif_get_int64</c>,
+ <c>enif_get_uint64</c>, <c>enif_make_int64</c>,
+ <c>enif_make_uint64</c>.</p>
+ <p>
+ Own Id: OTP-8746</p>
+ </item>
+ <item>
+ <p>
+ Alignment of trailing data in messages has been adjusted.
+ This in order to be able to pass data of any type as
+ trailing data in the future.</p>
+ <p>
+ Own Id: OTP-8754</p>
+ </item>
+ <item>
+ <p>
+ The obsolete/driver.h header file has been removed. It
+ has been obsolete and deprecated since R8B. Drivers that
+ still include obsolete/driver.h must be updated to
+ include erl_driver.h.</p>
+ <p>
+ *** POTENTIAL INCOMPATIBILITY ***</p>
+ <p>
+ Own Id: OTP-8758</p>
+ </item>
+ <item>
+ <p>
+ Added erlang:system_info(build_type) which makes it
+ easier to chose drivers, NIF libraries, etc based on
+ build type of the runtime system.</p>
+ <p>
+ The NIF library for crypto can now be built for valgrind
+ and/or debug as separate NIF libraries that will be
+ automatically loaded if the runtime system has been built
+ with a matching build type.</p>
+ <p>
+ Own Id: OTP-8760</p>
+ </item>
+ <item>
+ <p>
+ Further lessened the memory requirements of ETS objects.</p>
+ <p>
+ Own Id: OTP-8762</p>
+ </item>
+ <item>
+ <p>The broken elib_malloc alternate memory allocator has
+ been removed. <c>erlang:system_info(elib_malloc)</c> will
+ always return <c>false</c>, and in R15,
+ <c>erlang:system_info(elib_malloc)</c> will fail with a
+ <c>badarg</c> exception.</p>
+ <p>
+ Own Id: OTP-8764</p>
+ </item>
+ <item>
+ <p>
+ Calling <c>erlang:system_info/1</c> with the new argument
+ <c>update_cpu_info</c> will make the runtime system
+ reread and update the internally stored CPU information.
+ For more information see the documentation of <seealso
+ marker="erlang#update_cpu_info">erlang:system_info(update_cpu_info)</seealso>.</p>
+ <p>
+ The CPU topology is now automatically detected on Windows
+ systems with less than 33 logical processors. The runtime
+ system will now, also on Windows, by default bind
+ schedulers to logical processors using the
+ <c>default_bind</c> bind type if the amount of schedulers
+ is at least equal to the amount of logical processors
+ configured, binding of schedulers is supported, and a CPU
+ topology is available at startup.</p>
+ <p>
+ Own Id: OTP-8765</p>
+ </item>
+ <item>
+ <p>
+ The SMP ERTS internal child waiter thread used on Linux
+ system with NPTL was unintentionally disabled during
+ cross compilation rewrites (OTP-8323 in R13B03). It has
+ now been re-enabled. Enabling it again gives a slight
+ performance improvement.</p>
+ <p>
+ Own Id: OTP-8774</p>
+ </item>
+ <item>
+ <p>
+ <c>epmd</c> used to generate a message to the syslog when
+ it started up, which could be annoying. This has been
+ changed to only generate the message if the debug swith
+ is given. (Thanks to Michael Santos.)</p>
+ <p>
+ Own Id: OTP-8775</p>
+ </item>
+ <item>
+ <p>
+ The scheduler wakeup threshold is now possible to adjust
+ at system boot. For more information see the <seealso
+ marker="erl#+swt">+swt</seealso> command line argument of
+ <c>erl</c>.</p>
+ <p>
+ Own Id: OTP-8811</p>
+ </item>
+ <item>
+ <p>
+ The undocumented function inet:ifget/2 has been improved
+ to return interface hardware address (MAC) on platforms
+ supporting getaddrinfo() (such as BSD unixes). Note it
+ still does not work on all platforms for example not
+ Windows nor Solaris, so the function is still
+ undocumented.</p>
+ <p>
+ Buffer overflow and field init bugs for inet:ifget/2 and
+ inet:getservbyname/2 has also been fixed.</p>
+ <p>
+ Thanks to Michael Santos.</p>
+ <p>
+ Own Id: OTP-8816</p>
+ </item>
+ <item>
+ <p>
+ Optimizations for MIPS when using gcc atomics. (Thanks to
+ Steve Vinoski)</p>
+ <p>
+ Own Id: OTP-8834</p>
+ </item>
+ <item>
+ <p>
+ Lock optimization in timer functionality.</p>
+ <p>
+ Own Id: OTP-8835</p>
+ </item>
+ </list>
+ </section>
+
+
+ <section><title>Known Bugs and Problems</title>
+ <list>
+ <item>
+ <p>Fix epmd and build environment to build on VxWorks</p>
+ <p>
+ Own Id: OTP-8838</p>
+ </item>
+ </list>
+ </section>
+
+</section>
+
+<section><title>Erts 5.8</title>
+
+ <section><title>Fixed Bugs and Malfunctions</title>
+ <list>
+ <item>
+ <p>
+ Driver threads, such as async threads, using <seealso
+ marker="erl_driver#ErlDrvPDL">port data locks</seealso>
+ peeked at the port status field without proper locking
+ when looking up the driver queue.</p>
+ <p>
+ Own Id: OTP-8475</p>
+ </item>
+ <item>
+ <p>
+ The use of <c>mmap()</c> was unnecessarily disabled when
+ cross compiling.</p>
+ <p>
+ The <c>configure</c> arguments <c>--with-ssl</c>, and
+ <c>--with-odbc</c> refused to accept libraries outside of
+ <c>$erl_xcomp_sysroot</c> when cross compiling for no
+ good reason.</p>
+ <p>
+ The <c>configure</c> argument <c>--with-odbc</c> didn't
+ handle the value <c>yes</c> correct.</p>
+ <p>
+ The <c>configure</c> arguments <c>--with-odbc</c>, and
+ <c>--without-odbc</c> have also been added to the
+ configure help.</p>
+ <p>
+ (Thanks to Steve Vinoski for reporting these issues)</p>
+ <p>
+ Own Id: OTP-8484</p>
+ </item>
+ <item>
+ <p>
+ A call to the BIF <c>unregister(RegName)</c> when a port
+ had the name <c>RegName</c> registered in the runtime
+ system without SMP support caused a runtime system crash.
+ (Thanks to Per Hedeland for the bugfix and test case.)</p>
+ <p>
+ Own Id: OTP-8487</p>
+ </item>
+ <item>
+ <p>
+ The runtime system crashed if fewer logical processors
+ were found than reported by <c>sysconf(
+ SC_NPROCESSORS_CONF)</c>.</p>
+ <p>
+ Own Id: OTP-8549</p>
+ </item>
+ <item>
+ <p>
+ Fix memory management bug causing crash of non-SMP
+ emulator with async threads enabled. The bug did first
+ appear in R13B03.</p>
+ <p>
+ Own Id: OTP-8591 Aux Id: seq11554 </p>
+ </item>
+ <item>
+ <p>
+ Port locks could be prematurely destroyed.</p>
+ <p>
+ Own Id: OTP-8612</p>
+ </item>
+ <item>
+ <p>The <c>empd</c> program could loop and consume 100%
+ CPU time if an unexpected error ocurred in
+ <c>listen()</c> or <c>accept()</c>. Now <c>epmd</c> will
+ terminate if a non-recoverable error occurs. (Thanks to
+ Michael Santos.)</p>
+ <p>
+ Own Id: OTP-8618</p>
+ </item>
+ <item>
+ <p>
+ When kernel poll has been enabled, a livelock could in
+ rare circumstances occur. Problem reported by Chetan
+ Ahuja, fix by Mikael Pettersson.</p>
+ <p>
+ Own Id: OTP-8632</p>
+ </item>
+ <item>
+ <p>
+ Windows: Closing port of program that stalled without
+ reading all data could deadlock scheduler thread.</p>
+ <p>
+ Own Id: OTP-8641</p>
+ </item>
+ <item>
+ <p>
+ On some combination of Montavista Linux on Cavium Octeon
+ processors, some socket-related system calls returned
+ other numbers than -1 for errors. This caused a core dump
+ in inet_drv.c. Now the code works around this problem.</p>
+ <p>
+ Own Id: OTP-8654</p>
+ </item>
+ <item>
+ <p>
+ Missing memory barriers in <c>erts_poll()</c> could cause
+ the runtime system to hang indefinitely.</p>
+ <p>
+ Own Id: OTP-8658</p>
+ </item>
+ <item>
+ <p>
+ <c>ethr_rwmutex_tryrlock()</c> acquired and refused to
+ acquire a lock with inverted logic. The lock was however
+ never acquired in a thread unsafe manner. (Thanks to JR
+ Zhang for noting this issue)</p>
+ <p>
+ Own Id: OTP-8662</p>
+ </item>
+ <item>
+ <p>
+ Extreme combinations of register/unregister in a highly
+ parallell SMP application could crash the VM. The error
+ is corrected.</p>
+ <p>
+ Own Id: OTP-8663</p>
+ </item>
+ <item>
+ <p>
+ On Windows, files are now opened with FILE_SHARE_DELETE
+ to get closer to Unix semantics.</p>
+ <p>
+ Own Id: OTP-8667</p>
+ </item>
+ <item>
+ <p>
+ <c>erlang:system_info(multi_scheduling)</c> sometimes
+ erroneously returned <c>enabled</c> when it should have
+ returned <c>blocked</c>.</p>
+ <p>
+ Own Id: OTP-8675</p>
+ </item>
+ <item>
+ <p>
+ Fix bug causing <c>erlang:decode_packet</c> and
+ <c>enif_make_string</c> to generate faulty strings with
+ negative character values for ascii values larger than
+ 127. (Thanks to Paul Guyot)</p>
+ <p>
+ Own Id: OTP-8685</p>
+ </item>
+ <item>
+ <p>
+ <c>open_port/2</c> with the <c>spawn</c> and
+ <c>spawn_executable</c> options can include an
+ <c>{env,Env}</c> option. In some cases unsetting
+ variables would not work on Unix (typically if more
+ variables were unset than were actually present in the
+ environment).</p>
+ <p>
+ Own Id: OTP-8701</p>
+ </item>
+ <item>
+ <p>
+ A user defined CPU topology set via a call to <seealso
+ marker="erlang#system_flag_cpu_topology">erlang:system_flag(cpu_topology,
+ CPUTopology)</seealso> was not properly verified, and
+ could in worst case cause an emulator crash. The emulator
+ crash could only occur when a user defined CPU topology
+ already existed and was redefined.</p>
+ <p>
+ Own Id: OTP-8710</p>
+ </item>
+ </list>
+ </section>
+
+
+ <section><title>Improvements and New Features</title>
+ <list>
+ <item>
+ <p>
+ The grammar for match specifications in ERTS users guide
+ only described the tracing dialect of match
+ specifications. An informal grammar for the ETS dialect
+ is added.</p>
+ <p>
+ Own Id: OTP-8086 Aux Id: seq11333 </p>
+ </item>
+ <item>
+ <p>
+ The module binary from EEP31 (and EEP9) is implemented.</p>
+ <p>
+ Own Id: OTP-8217</p>
+ </item>
+ <item>
+ <p>
+ New NIF API function <c>enif_make_new_binary</c></p>
+ <p>
+ Own Id: OTP-8474</p>
+ </item>
+ <item>
+ <p>
+ The guard BIF <c>is_boolean/1</c> (introduced in R10B)
+ has now been included in the lists of BIFs allowed in
+ guards in the Reference Manual.</p>
+ <p>
+ Own Id: OTP-8477</p>
+ </item>
+ <item>
+ <p>
+ Added function <c>zip:foldl/3</c> to iterate over zip
+ archives.</p>
+ <p>
+ Added functions to create and extract escripts. See
+ <c>escript:create/2</c> and <c>escript:extract/2</c>.</p>
+ <p>
+ The undocumented function <c>escript:foldl/3</c> has been
+ removed. The same functionality can be achieved with the
+ more flexible functions <c>escript:extract/2</c> and
+ <c>zip:foldl/3</c>.</p>
+ <p>
+ Record fields has been annotated with type info. Source
+ files as been adapted to fit within 80 chars and trailing
+ whitespace has been removed.</p>
+ <p>
+ Own Id: OTP-8521</p>
+ </item>
+ <item>
+ <p>A regular expression with many levels of parenthesis
+ could cause a buffer overflow. That has been corrected.
+ (Thanks to Michael Santos.)</p>
+ <p>
+ Own Id: OTP-8539</p>
+ </item>
+ <item>
+ <p>
+ <c>erlang:decode_packet(httph_bin,..)</c> could return
+ corrupt header strings or even crash the VM. This has
+ been fixed. It only happened on 32-bit VM if the header
+ name was unknown and between 16 and 20 characters long.
+ Sockets with simular <c>packet</c> option did not suffer
+ from this bug.</p>
+ <p>
+ Own Id: OTP-8548</p>
+ </item>
+ <item>
+ <p>New NIF features:</p> <list><item> Send messages from
+ a NIF, or from thread created by NIF, to any local
+ process (<c>enif_send</c>) </item><item> Store terms
+ between NIF calls (<c>enif_alloc_env</c>,
+ <c>enif_make_copy</c>) </item><item> Create binary terms
+ with user defined memory management
+ (<c>enif_make_resource_binary</c>) </item></list> <p>And
+ some incompatible changes made to the API. For more
+ information see the warning text in <seealso
+ marker="erl_nif">erl_nif(3)</seealso>.</p>
+ <p>
+ *** POTENTIAL INCOMPATIBILITY ***</p>
+ <p>
+ Own Id: OTP-8555</p>
+ </item>
+ <item>
+ <p>If the '<c>fop</c>' program (needed for building PDF
+ files) cannot not be found, it is now possible to build
+ the HTML and man pages anyway (there will also be dummy
+ PDF files with no real content created). (Thanks to
+ Tuncer Ayaz.)</p>
+ <p>
+ Own Id: OTP-8559</p>
+ </item>
+ <item>
+ <p>When defining macros the closing right parenthesis
+ before the dot is now mandatory.</p>
+ <p>
+ *** POTENTIAL INCOMPATIBILITY ***</p>
+ <p>
+ Own Id: OTP-8562</p>
+ </item>
+ <item>
+ <p>Local and imported functions now override the
+ auto-imported BIFs when the names clash. The pre R14
+ behaviour was that auto-imported BIFs would override
+ local functions. To avoid that old programs change
+ behaviour, the following will generate an error:</p>
+ <list><item><p>Doing a call without explicit module name
+ to a local function having a name clashing with the name
+ of an auto-imported BIF that was present (and
+ auto-imported) before OTP R14A</p></item>
+ <item><p>Explicitly importing a function having a name
+ clashing with the name of an autoimported BIF that was
+ present (and autoimported) before OTP R14A</p></item>
+ <item><p>Using any form of the old compiler directive
+ <c>nowarn_bif_clash</c></p></item> </list> <p>If the BIF
+ was added or auto-imported in OTP R14A or later,
+ overriding it with an import or a local function will
+ only result in a warning,</p> <p>To resolve clashes, you
+ can either use the explicit module name <c>erlang</c> to
+ call the BIF, or you can remove the auto-import of that
+ specific BIF by using the new compiler directive
+ <c>-compile({no_auto_import,[F/A]}).</c>, which makes all
+ calls to the local or imported function without explicit
+ module name pass without warnings or errors.</p> <p>The
+ change makes it possible to add auto-imported BIFs
+ without breaking or silently changing old code in the
+ future. However some current code ingeniously utilizing
+ the old behaviour or the <c>nowarn_bif_clash</c> compiler
+ directive, might need changing to be accepted by the
+ compiler.</p>
+ <p>
+ *** POTENTIAL INCOMPATIBILITY ***</p>
+ <p>
+ Own Id: OTP-8579</p>
+ </item>
+ <item>
+ <p>
+ A bug in re that could cause certain regular expression
+ matches never to terminate is corrected. (Thanks to
+ Michael Santos and Gordon Guthrie.)</p>
+ <p>
+ Own Id: OTP-8589</p>
+ </item>
+ <item>
+ <p>The erlang:open_port spawn and spawn_executable
+ directives can include an <c>{env,Env}</c> directive to
+ set up environment variables for the spawned process. A
+ bug prevented applications from using <c>{env,Env}</c> to
+ set an environment variable whose value ended with a
+ '<c>=</c>' (equal sign) character; the trailing equal
+ sign was mistaken as an indication that an environment
+ variable was to be cleared from the environment of the
+ spawned process. (Thanks to Steve Vinoski.)</p>
+ <p>
+ Own Id: OTP-8614</p>
+ </item>
+ <item>
+ <p><c>receive</c> statements that can only read out a
+ newly created reference are now specially optimized so
+ that it will execute in constant time regardless of the
+ number of messages in the receive queue for the process.
+ That optimization will benefit calls to
+ <c>gen_server:call()</c>. (See <c>gen:do_call/4</c> for
+ an example of a receive statement that will be
+ optimized.)</p>
+ <p>
+ Own Id: OTP-8623</p>
+ </item>
+ <item>
+ <p>
+ The functions file:advise/4 and file:datasync/1 have been
+ added. (Thanks to Filipe David Manana.)</p>
+ <p>
+ Own Id: OTP-8637</p>
+ </item>
+ <item>
+ <p>
+ New NIF API functions: <c>enif_make_atom_len</c>,
+ <c>enif_make_existing_atom_len</c>,
+ <c>enif_make_string_len</c>, <c>enif_get_atom_length</c>,
+ <c>enif_get_list_length</c>, <c>enif_is_list</c>,
+ <c>enif_is_tuple</c> (by Tuncer Ayaz)</p>
+ <p>
+ Own Id: OTP-8640</p>
+ </item>
+ <item>
+ <p>
+ Support for using gcc's built-in functions for atomic
+ memory access has been added. This functionallity will be
+ used if available and no other native atomic
+ implementation in ERTS is available.</p>
+ <p>
+ Own Id: OTP-8659</p>
+ </item>
+ <item>
+ <p>
+ The number of spinlocks used when implementing atomic
+ fall-backs when no native atomic implementation is
+ available has been increased from 16 to 1024.</p>
+ <p>
+ Own Id: OTP-8660</p>
+ </item>
+ <item>
+ <p>
+ Writer preferred pthread read/write locks has been
+ enabled on Linux.</p>
+ <p>
+ Own Id: OTP-8661</p>
+ </item>
+ <item>
+ <p>
+ The runtime system will by default bind schedulers to
+ logical processors using the <c>default_bind</c> bind
+ type if the amount of schedulers are at least equal to
+ the amount of logical processors configured, binding of
+ schedulers is supported, and a CPU topology is available
+ at startup. </p>
+ <p>
+ <em>NOTE:</em> If the Erlang runtime system is the only
+ operating system process that binds threads to logical
+ processors, this improves the performance of the runtime
+ system. However, if other operating system processes (as
+ for example another Erlang runtime system) also bind
+ threads to logical processors, there might be a
+ performance penalty instead. If this is the case you, are
+ are advised to unbind the schedulers using the <seealso
+ marker="erl#+sbt">+sbtu</seealso> command line argument,
+ or by invoking <seealso
+ marker="erlang#system_flag_scheduler_bind_type">erlang:system_flag(scheduler_bind_type,
+ unbound)</seealso>.</p>
+ <p>
+ Own Id: OTP-8666</p>
+ </item>
+ <item>
+ <p>
+ The recently added BIFs erlang:min/2, erlang:max/2 and
+ erlang:port_command/3 are now auto-imported (as they were
+ originally intended to be). Due to the recent compiler
+ change (OTP-8579), the only impact on old code defining
+ it's own min/2, max/2 or port_command/3 functions will be
+ a warning, the local functions will still be used. The
+ warning can be removed by using
+ -compile({no_auto_import,[min/2,max/2,port_command/3]}).
+ in the source file.</p>
+ <p>
+ *** POTENTIAL INCOMPATIBILITY ***</p>
+ <p>
+ Own Id: OTP-8669 Aux Id: OTP-8579 </p>
+ </item>
+ <item>
+ <p>
+ There is a new option 'exclusive' to file:open/2 that
+ uses the OS O_EXCL flag where supported to open the file
+ in exclusive mode.</p>
+ <p>
+ Own Id: OTP-8670</p>
+ </item>
+ <item>
+ <p>
+ Now, binary_to_term/2 is auto-imported. This will cause a
+ compile warning if and only if a module has got a local
+ function with that name.</p>
+ <p>
+ *** POTENTIAL INCOMPATIBILITY ***</p>
+ <p>
+ Own Id: OTP-8671</p>
+ </item>
+ <item>
+ <p>
+ Alignment of scheduler data and run queues were adjusted.</p>
+ <p>
+ Own Id: OTP-8673</p>
+ </item>
+ <item>
+ <p>Call time breakpoint tracing</p> <list><item>Introduce
+ a <c>call_time</c> option to
+ <c>erlang:trace_pattern/3</c>.This option enables call
+ time breakpoint tracing on code that is executed by
+ processes with call tracing enabled. Call time tracing
+ stores the number of calls and the time spent of each
+ function with this trace pattern enabled. The information
+ can be retrieved with <c>erlang:trace_info/2</c></item>
+ <item>Add a scheduler array for BpData. To solve the
+ issue of multiple schedulers constantly updating the head
+ pointer to the bp data wheel, each scheduler now has its
+ own entrypoint to the wheel. This head pointer can be
+ updated without a locking being taken.</item></list>
+ <p>Teach call count tracing to use atomics</p>
+ <list><item>Call count previously used a global lock for
+ accessing and writing its counter in the breakpoint. This
+ is now changed to atomics instead.</item> <item>The
+ change will let call count tracing and cprof to scale
+ better when increasing the number of
+ schedulers.</item></list>
+ <p>
+ Own Id: OTP-8677</p>
+ </item>
+ <item>
+ <p><c>eprof</c> has been reimplemented with support in
+ the Erlang virtual machine and is now both faster (i.e.
+ slows down the code being measured less) and scales much
+ better. In measurements we saw speed-ups compared to the
+ old eprof ranging from 6 times (for sequential code that
+ only uses one scheduler/core) up to 84 times (for
+ parallel code that uses 8 cores).</p>
+ <p>Note: The API for the <c>eprof</c> has been cleaned up
+ and extended. See the documentation.</p>
+ <p>
+ *** POTENTIAL INCOMPATIBILITY ***</p>
+ <p>
+ Own Id: OTP-8706</p>
+ </item>
+ </list>
+ </section>
+
+</section>
+
<section><title>Erts 5.7.5.2</title>
<section><title>Known Bugs and Problems</title>
@@ -162,7 +2419,7 @@
<item>
<p>A number of bugs concerning re and unicode are
corrected:</p>
- <p>re:compile no longer looses unicode option, which also
+ <p>re:compile no longer loses unicode option, which also
fixes bug in re:split.</p>
<p>re:replace now handles unicode charlist replacement
argument</p>
@@ -2633,7 +4890,7 @@
The race occurred when a process removed a table during
termination simultaneously as another process removed the
same table via <c>ets:delete/1</c> and a third process
- created a table that accidentaly got the same internal
+ created a table that accidentally got the same internal
table index as the table being removed.</p>
<p>
Own Id: OTP-7349</p>
@@ -4734,7 +6991,7 @@
</item>
<item>
<p>The runtime system with SMP support did not slowly adjust
- it's view of time when the system time suddenly changed.</p>
+ its view of time when the system time suddenly changed.</p>
<p>Timeouts could sometimes timeout too early on the runtime
system with SMP support.</p>
<p>Own Id: OTP-6202</p>
diff --git a/erts/doc/src/run_erl.xml b/erts/doc/src/run_erl.xml
index 7bf7f559c5..c9784299b3 100644
--- a/erts/doc/src/run_erl.xml
+++ b/erts/doc/src/run_erl.xml
@@ -4,7 +4,7 @@
<comref>
<header>
<copyright>
- <year>1999</year><year>2009</year>
+ <year>1999</year><year>2011</year>
<holder>Ericsson AB. All Rights Reserved.</holder>
</copyright>
<legalnotice>
@@ -144,6 +144,14 @@
<item>The size (in bytes) of a log file before switching to a
new log file. Default is 100000, minimum is 1000 and maximum is
approximately 2^30.</item>
+ <tag>RUN_ERL_DISABLE_FLOWCNTRL</tag>
+ <item>If defined, disables input and output flow control for the pty opend by run_erl.
+ Useful if you want to remove any risk of accidentally blocking the flow control
+ by hit Ctrl-S (instead of Ctrl-D to detach).
+ Which may result in blocking of the entire beam process
+ and in the case of running heart as supervisor
+ even the heart process will be blocked when writing log message to terminal.
+ Leaving the heart process unable to do its work.</item>
</taglist>
</section>
diff --git a/erts/doc/src/specs.xml b/erts/doc/src/specs.xml
new file mode 100644
index 0000000000..e5c2f4783f
--- /dev/null
+++ b/erts/doc/src/specs.xml
@@ -0,0 +1,7 @@
+<?xml version="1.0" encoding="latin1" ?>
+<specs xmlns:xi="http://www.w3.org/2001/XInclude">
+ <xi:include href="../specs/specs_erl_prim_loader.xml"/>
+ <xi:include href="../specs/specs_erlang.xml"/>
+ <xi:include href="../specs/specs_init.xml"/>
+ <xi:include href="../specs/specs_zlib.xml"/>
+</specs>
diff --git a/erts/doc/src/start_erl.xml b/erts/doc/src/start_erl.xml
index 21cc901f52..92d87b095a 100644
--- a/erts/doc/src/start_erl.xml
+++ b/erts/doc/src/start_erl.xml
@@ -4,7 +4,7 @@
<comref>
<header>
<copyright>
- <year>1998</year><year>2009</year>
+ <year>1998</year><year>2011</year>
<holder>Ericsson AB. All Rights Reserved.</holder>
</copyright>
<legalnotice>
@@ -69,12 +69,29 @@
<c><![CDATA[erl]]></c> program. Everything <em>after</em><c><![CDATA[++]]></c> is
interpreted as options to <c><![CDATA[start_erl]]></c> itself.</item>
<tag>-reldir &lt;release root&gt;</tag>
- <item>Mandatory if the environment variable <c><![CDATA[RELDIR]]></c> is not
- specified. Tells start_erl where the root of the
- release tree is placed in the file-system
- (like &lt;Erlang root&gt;\\releases). The
- <c><![CDATA[start_erl.data]]></c> file is expected to be placed in
- this directory (if not otherwise specified).</item>
+
+ <item>Mandatory if the environment variable
+ <c><![CDATA[RELDIR]]></c> is not specified and no
+ <c>-rootdir</c> option is given. Tells start_erl where the
+ root of the release tree is placed in the file-system (typically
+ &lt;Erlang root&gt;\\releases). The
+ <c><![CDATA[start_erl.data]]></c> file is expected to be
+ placed in this directory (if not otherwise specified). If
+ only the <c>-rootdir</c> option is given, the directory is
+ assumed to be &lt;Erlang root&gt;\\releases.</item>
+
+ <tag>-rootdir &lt;Erlang root directory&gt;</tag>
+
+ <item>Mandatory if <c>-reldir</c> is not given and there is
+ no <c><![CDATA[RELDIR]]></c> in the environment. This
+ specifies the Erlang installation root directory (under
+ which the <c>lib</c>, <c>releases</c> and
+ <c>erts-&lt;Version&gt;</c> directories are placed). If only
+ <c>-reldir</c> (or the environment variable
+ <c><![CDATA[RELDIR]]></c>) is given, the Erlang root is assumed to
+ be the directory exactly one level above the release
+ directory.</item>
+
<tag>-data &lt;data file name&gt;</tag>
<item>Optional, specifies another data file than start_erl.data
in the &lt;release root&gt;. It is specified relative to the
diff --git a/erts/doc/src/zlib.xml b/erts/doc/src/zlib.xml
index b1e768bce9..8917ab5c3a 100644
--- a/erts/doc/src/zlib.xml
+++ b/erts/doc/src/zlib.xml
@@ -4,7 +4,7 @@
<erlref>
<header>
<copyright>
- <year>2005</year><year>2010</year>
+ <year>2005</year><year>2011</year>
<holder>Ericsson AB. All Rights Reserved.</holder>
</copyright>
<legalnotice>
@@ -76,96 +76,92 @@ list_to_binary([Compressed|Last])</pre>
</taglist>
</description>
- <section>
- <title>DATA TYPES</title>
- <code type="none">
-iodata = iolist() | binary()
-
-iolist = [char() | binary() | iolist()]
- a binary is allowed as the tail of the list
-
-zstream = a zlib stream, see open/0</code>
- </section>
+ <datatypes>
+ <datatype>
+ <name name="zstream"/>
+ <desc>
+ <p>A zlib stream, see <seealso marker="#open/0">open/0</seealso>.
+ </p>
+ </desc>
+ </datatype>
+ <datatype>
+ <name name="zlevel"/>
+ </datatype>
+ <datatype>
+ <name name="zmemlevel"/>
+ </datatype>
+ <datatype>
+ <name name="zmethod"/>
+ </datatype>
+ <datatype>
+ <name name="zstrategy"/>
+ </datatype>
+ <datatype>
+ <name name="zwindowbits"/>
+ <desc>
+ <p>Normally in the range <c>-15..-9 | 9..15</c>.</p>
+ </desc>
+ </datatype>
+ </datatypes>
<funcs>
<func>
- <name>open() -> Z </name>
+ <name name="open" arity="0"/>
<fsummary>Open a stream and return a stream reference</fsummary>
- <type>
- <v>Z = zstream()</v>
- </type>
<desc>
<p>Open a zlib stream.</p>
</desc>
</func>
<func>
- <name>close(Z) -> ok</name>
+ <name name="close" arity="1"/>
<fsummary>Close a stream</fsummary>
- <type>
- <v>Z = zstream()</v>
- </type>
<desc>
- <p>Closes the stream referenced by <c>Z</c>.</p>
+ <p>Closes the stream referenced by <c><anno>Z</anno></c>.</p>
</desc>
</func>
<func>
- <name>deflateInit(Z) -> ok</name>
+ <name name="deflateInit" arity="1"/>
<fsummary>Initialize a session for compression</fsummary>
- <type>
- <v>Z = zstream()</v>
- </type>
<desc>
- <p>Same as <c>zlib:deflateInit(Z, default)</c>.</p>
+ <p>Same as <c>zlib:deflateInit(<anno>Z</anno>, default)</c>.</p>
</desc>
</func>
<func>
- <name>deflateInit(Z, Level) -> ok</name>
+ <name name="deflateInit" arity="2"/>
<fsummary>Initialize a session for compression</fsummary>
- <type>
- <v>Z = zstream()</v>
- <v>Level = none | default | best_speed | best_compression | 0..9</v>
- </type>
<desc>
<p>Initialize a zlib stream for compression.</p>
- <p><c>Level</c> decides the compression level to be used, 0
+ <p><c><anno>Level</anno></c> decides the compression level to be used, 0
(<c>none</c>), gives no compression at all, 1
(<c>best_speed</c>) gives best speed and 9
(<c>best_compression</c>) gives best compression.</p>
</desc>
</func>
<func>
- <name>deflateInit(Z, Level, Method, WindowBits, MemLevel, Strategy) -> ok</name>
+ <name name="deflateInit" arity="6"/>
<fsummary>Initialize a session for compression</fsummary>
- <type>
- <v>Z = zstream()</v>
- <v>Level = none | default | best_speed | best_compression | 0..9</v>
- <v>Method = deflated</v>
- <v>WindowBits = 9..15|-9..-15</v>
- <v>MemLevel = 1..9</v>
- <v>Strategy = default|filtered|huffman_only</v>
- </type>
<desc>
<p>Initiates a zlib stream for compression.</p>
- <p>The <c>Level</c> parameter decides the compression level to be
+ <p>The <c><anno>Level</anno></c> parameter decides the compression level to be
used, 0 (<c>none</c>), gives no compression at all, 1
(<c>best_speed</c>) gives best speed and 9
(<c>best_compression</c>) gives best compression.</p>
- <p>The <c>Method</c> parameter decides which compression method to use,
+ <p>The <c><anno>Method</anno></c> parameter decides which compression method to use,
currently the only supported method is <c>deflated</c>.</p>
- <p>The <c>WindowBits</c> parameter is the base two logarithm
+ <p>The <c><anno>WindowBits</anno></c> parameter is the base two logarithm
of the window size (the size of the history buffer). It
should be in the range 9 through 15. Larger values
of this parameter result in better compression at the
expense of memory usage. The default value is 15 if
- <c>deflateInit/2</c>. A negative <c>WindowBits</c>
+ <c>deflateInit/2</c>. A negative <c><anno>WindowBits</anno></c>
value suppresses the zlib header (and checksum) from the
stream. Note that the zlib source mentions this only as a
undocumented feature.</p>
- <p>The <c>MemLevel</c> parameter specifies how much memory
+ <p>The <c><anno>MemLevel</anno></c> parameter specifies how much memory
should be allocated for the internal compression
- state. <c>MemLevel</c>=1 uses minimum memory but is slow and
- reduces compression ratio; <c>MemLevel</c>=9 uses maximum
+ state. <c><anno>MemLevel</anno></c>=1 uses minimum memory but is slow and
+ reduces compression ratio; <c><anno>MemLevel</anno></c>=9 uses maximum
memory for optimal speed. The default value is 8.</p>
- <p>The <c>Strategy</c> parameter is used to tune the
+ <p>The <c><anno>Strategy</anno></c> parameter is used to tune the
compression algorithm. Use the value <c>default</c> for
normal data, <c>filtered</c> for data produced by a filter
(or predictor), or <c>huffman_only</c> to force Huffman
@@ -175,54 +171,43 @@ zstream = a zlib stream, see open/0</code>
tuned to compress them better. The effect of
<c>filtered</c>is to force more Huffman coding and less
string matching; it is somewhat intermediate between
- <c>default</c> and <c>huffman_only</c>. The <c>Strategy</c>
+ <c>default</c> and <c>huffman_only</c>. The <c><anno>Strategy</anno></c>
parameter only affects the compression ratio but not the
correctness of the compressed output even if it is not set
appropriately.</p>
</desc>
</func>
<func>
- <name>deflate(Z, Data) -> Compressed</name>
+ <name name="deflate" arity="2"/>
<fsummary>Compress data</fsummary>
- <type>
- <v>Z = zstream()</v>
- <v>Data = iodata()</v>
- <v>Compressed = iolist()</v>
- </type>
<desc>
- <p>Same as <c>deflate(Z, Data, none)</c>.</p>
+ <p>Same as <c>deflate(<anno>Z</anno>, <anno>Data</anno>, none)</c>.</p>
</desc>
</func>
<func>
- <name>deflate(Z, Data, Flush) -> </name>
+ <name name="deflate" arity="3"/>
<fsummary>Compress data</fsummary>
- <type>
- <v>Z = zstream()</v>
- <v>Data = iodata()</v>
- <v>Flush = none | sync | full | finish</v>
- <v>Compressed = iolist()</v>
- </type>
<desc>
<p><c>deflate/3</c> compresses as much data as possible, and
stops when the input buffer becomes empty. It may introduce
some output latency (reading input without producing any
output) except when forced to flush.</p>
- <p>If the parameter <c>Flush</c> is set to <c>sync</c>, all
+ <p>If the parameter <c><anno>Flush</anno></c> is set to <c>sync</c>, all
pending output is flushed to the output buffer and the
output is aligned on a byte boundary, so that the
decompressor can get all input data available so far.
Flushing may degrade compression for some compression algorithms and so
it should be used only when necessary.</p>
- <p>If <c>Flush</c> is set to <c>full</c>, all output is flushed as with
+ <p>If <c><anno>Flush</anno></c> is set to <c>full</c>, all output is flushed as with
<c>sync</c>, and the compression state is reset so that decompression can
restart from this point if previous compressed data has been damaged or if
random access is desired. Using <c>full</c> too often can seriously degrade
the compression.</p>
- <p>If the parameter <c>Flush</c> is set to <c>finish</c>,
+ <p>If the parameter <c><anno>Flush</anno></c> is set to <c>finish</c>,
pending input is processed, pending output is flushed and
<c>deflate/3</c> returns. Afterwards the only possible
operations on the stream are <c>deflateReset/1</c> or <c>deflateEnd/1</c>.</p>
- <p><c>Flush</c> can be set to <c>finish</c> immediately after
+ <p><c><anno>Flush</anno></c> can be set to <c>finish</c> immediately after
<c>deflateInit</c> if all compression is to be done in one step.</p>
<pre>
@@ -234,13 +219,8 @@ list_to_binary([B1,B2])</pre>
</desc>
</func>
<func>
- <name>deflateSetDictionary(Z, Dictionary) -> Adler32</name>
+ <name name="deflateSetDictionary" arity="2"/>
<fsummary>Initialize the compression dictionary</fsummary>
- <type>
- <v>Z = zstream()</v>
- <v>Dictionary = binary()</v>
- <v>Adler32 = integer()</v>
- </type>
<desc>
<p>Initializes the compression dictionary from the given byte
sequence without producing any compressed output. This
@@ -253,11 +233,8 @@ list_to_binary([B1,B2])</pre>
</desc>
</func>
<func>
- <name>deflateReset(Z) -> ok</name>
+ <name name="deflateReset" arity="1"/>
<fsummary>Reset the deflate session</fsummary>
- <type>
- <v>Z = zstream()</v>
- </type>
<desc>
<p>This function is equivalent to <c>deflateEnd/1</c>
followed by <c>deflateInit/[1|2|6]</c>, but does not free
@@ -267,34 +244,26 @@ list_to_binary([B1,B2])</pre>
</desc>
</func>
<func>
- <name>deflateParams(Z, Level, Strategy) -> ok </name>
+ <name name="deflateParams" arity="3"/>
<fsummary>Dynamicly update deflate parameters</fsummary>
- <type>
- <v>Z = zstream()</v>
- <v>Level = none | default | best_speed | best_compression | 0..9</v>
- <v>Strategy = default|filtered|huffman_only</v>
- </type>
<desc>
<p>Dynamically update the compression level and compression
- strategy. The interpretation of <c>Level</c> and
- <c>Strategy</c> is as in <c>deflateInit/6</c>. This can be
+ strategy. The interpretation of <c><anno>Level</anno></c> and
+ <c><anno>Strategy</anno></c> is as in <c>deflateInit/6</c>. This can be
used to switch between compression and straight copy of the
input data, or to switch to a different kind of input data
requiring a different strategy. If the compression level is
changed, the input available so far is compressed with the
old level (and may be flushed); the new level will take
effect only at the next call of <c>deflate/3</c>.</p>
- <p>Before the call of deflateParams, the stream state must be set as for
+ <p>Before the call of <c>deflateParams</c>, the stream state must be set as for
a call of <c>deflate/3</c>, since the currently available input may have to
be compressed and flushed.</p>
</desc>
</func>
<func>
- <name>deflateEnd(Z) -> ok</name>
+ <name name="deflateEnd" arity="1"/>
<fsummary>End deflate session</fsummary>
- <type>
- <v>Z = zstream()</v>
- </type>
<desc>
<p>End the deflate session and cleans all data used.
Note that this function will throw an <c>data_error</c>
@@ -304,43 +273,31 @@ list_to_binary([B1,B2])</pre>
</desc>
</func>
<func>
- <name>inflateInit(Z) -> ok </name>
+ <name name="inflateInit" arity="1"/>
<fsummary>Initialize a session for decompression</fsummary>
- <type>
- <v>Z = zstream()</v>
- </type>
<desc>
<p>Initialize a zlib stream for decompression.</p>
</desc>
</func>
<func>
- <name>inflateInit(Z, WindowBits) -> ok </name>
+ <name name="inflateInit" arity="2"/>
<fsummary>Initialize a session for decompression</fsummary>
- <type>
- <v>Z = zstream()</v>
- <v>WindowBits = 9..15|-9..-15</v>
- </type>
<desc>
<p>Initialize decompression session on zlib stream.</p>
- <p>The <c>WindowBits</c> parameter is the base two logarithm
+ <p>The <c><anno>WindowBits</anno></c> parameter is the base two logarithm
of the maximum window size (the size of the history buffer).
It should be in the range 9 through 15.
The default value is 15 if <c>inflateInit/1</c> is used.
If a compressed stream with a larger window size is
given as input, inflate() will throw the <c>data_error</c>
- exception. A negative <c>WindowBits</c> value makes zlib ignore the
+ exception. A negative <c><anno>WindowBits</anno></c> value makes zlib ignore the
zlib header (and checksum) from the stream. Note that the zlib
source mentions this only as a undocumented feature.</p>
</desc>
</func>
<func>
- <name>inflate(Z, Data) -> DeCompressed </name>
+ <name name="inflate" arity="2"/>
<fsummary>Decompress data</fsummary>
- <type>
- <v>Z = zstream()</v>
- <v>Data = iodata()</v>
- <v>DeCompressed = iolist()</v>
- </type>
<desc>
<p><c>inflate/2</c> decompresses as much data as possible.
It may some introduce some output latency (reading
@@ -353,12 +310,8 @@ list_to_binary([B1,B2])</pre>
</desc>
</func>
<func>
- <name>inflateSetDictionary(Z, Dictionary) -> ok</name>
+ <name name="inflateSetDictionary" arity="2"/>
<fsummary>Initialize the decompression dictionary</fsummary>
- <type>
- <v>Z = zstream()</v>
- <v>Dictionary = binary()</v>
- </type>
<desc>
<p>Initializes the decompression dictionary from the given
uncompressed byte sequence. This function must be called
@@ -381,11 +334,8 @@ unpack(Z, Compressed, Dict) ->
</desc>
</func>
<func>
- <name>inflateReset(Z) -> ok</name>
+ <name name="inflateReset" arity="1"/>
<fsummary>>Reset the inflate session</fsummary>
- <type>
- <v>Z = zstream()</v>
- </type>
<desc>
<p>This function is equivalent to <c>inflateEnd/1</c> followed
by <c>inflateInit/1</c>, but does not free and reallocate all
@@ -394,11 +344,8 @@ unpack(Z, Compressed, Dict) ->
</desc>
</func>
<func>
- <name>inflateEnd(Z) -> ok</name>
+ <name name="inflateEnd" arity="1"/>
<fsummary>End inflate session</fsummary>
- <type>
- <v>Z = zstream()</v>
- </type>
<desc>
<p>End the inflate session and cleans all data used. Note
that this function will throw a <c>data_error</c> exception
@@ -407,198 +354,132 @@ unpack(Z, Compressed, Dict) ->
</desc>
</func>
<func>
- <name>setBufSize(Z, Size) -> ok</name>
+ <name name="setBufSize" arity="2"/>
<fsummary>Set buffer size</fsummary>
- <type>
- <v>Z = zstream()</v>
- <v>Size = integer()</v>
- </type>
<desc>
<p>Sets the intermediate buffer size.</p>
</desc>
</func>
<func>
- <name>getBufSize(Z) -> Size</name>
+ <name name="getBufSize" arity="1"/>
<fsummary>Get buffer size</fsummary>
- <type>
- <v>Z = zstream()</v>
- <v>Size = integer()</v>
- </type>
<desc>
<p>Get the size of intermediate buffer.</p>
</desc>
</func>
<func>
- <name>crc32(Z) -> CRC</name>
+ <name name="crc32" arity="1"/>
<fsummary>Get current CRC</fsummary>
- <type>
- <v>Z = zstream()</v>
- <v>CRC = integer()</v>
- </type>
<desc>
<p>Get the current calculated CRC checksum.</p>
</desc>
</func>
<func>
- <name>crc32(Z, Binary) -> CRC</name>
+ <name name="crc32" arity="2"/>
<fsummary>Calculate CRC</fsummary>
- <type>
- <v>Z = zstream()</v>
- <v>Binary = binary()</v>
- <v>CRC = integer()</v>
- </type>
<desc>
- <p>Calculate the CRC checksum for <c>Binary</c>.</p>
+ <p>Calculate the CRC checksum for <c><anno>Data</anno></c>.</p>
</desc>
</func>
<func>
- <name>crc32(Z, PrevCRC, Binary) -> CRC </name>
+ <name name="crc32" arity="3"/>
<fsummary>Calculate CRC</fsummary>
- <type>
- <v>Z = zstream()</v>
- <v>PrevCRC = integer()</v>
- <v>Binary = binary()</v>
- <v>CRC = integer()</v>
- </type>
- <desc>
- <p>Update a running CRC checksum for <c>Binary</c>.
- If <c>Binary</c> is the empty binary, this function returns
+ <desc>
+ <p>Update a running CRC checksum for <c><anno>Data</anno></c>.
+ If <c><anno>Data</anno></c> is the empty binary or the empty iolist, this function returns
the required initial value for the crc.</p>
<pre>
-Crc = lists:foldl(fun(Bin,Crc0) ->
- zlib:crc32(Z, Crc0, Bin),
- end, zlib:crc32(Z,&lt;&lt; &gt;&gt;), Bins)</pre>
+Crc = lists:foldl(fun(Data,Crc0) ->
+ zlib:crc32(Z, Crc0, Data),
+ end, zlib:crc32(Z,&lt;&lt; &gt;&gt;), Datas)</pre>
</desc>
</func>
<func>
- <name>crc32_combine(Z, CRC1, CRC2, Size2) -> CRC </name>
+ <name name="crc32_combine" arity="4"/>
<fsummary>Combine two CRC's</fsummary>
- <type>
- <v>Z = zstream()</v>
- <v>CRC = integer()</v>
- <v>CRC1 = integer()</v>
- <v>CRC2 = integer()</v>
- <v>Size2 = integer()</v>
- </type>
- <desc>
- <p>Combine two CRC checksums into one. For two binaries,
- <c>Bin1</c> and <c>Bin2</c> with sizes of <c>Size1</c> and
- <c>Size2</c>, with CRC checksums <c>CRC1</c> and
- <c>CRC2</c>. <c>crc32_combine/4</c> returns the <c>CRC</c>
- checksum of <c>&lt;&lt;Bin1/binary,Bin2/binary&gt;&gt;</c>, requiring
- only <c>CRC1</c>, <c>CRC2</c>, and <c>Size2</c>.
+ <desc>
+ <p>Combine two CRC checksums into one. For two binaries or iolists,
+ <c>Data1</c> and <c>Data2</c> with sizes of <c>Size1</c> and
+ <c><anno>Size2</anno></c>, with CRC checksums <c><anno>CRC1</anno></c> and
+ <c><anno>CRC2</anno></c>. <c>crc32_combine/4</c> returns the <c><anno>CRC</anno></c>
+ checksum of <c>[Data1,Data2]</c>, requiring
+ only <c><anno>CRC1</anno></c>, <c><anno>CRC2</anno></c>, and <c><anno>Size2</anno></c>.
</p>
</desc>
</func>
<func>
- <name>adler32(Z, Binary) -> Checksum</name>
+ <name name="adler32" arity="2"/>
<fsummary>Calculate the adler checksum</fsummary>
- <type>
- <v>Z = zstream()</v>
- <v>Binary = binary()</v>
- <v>Checksum = integer()</v>
- </type>
<desc>
- <p>Calculate the Adler-32 checksum for <c>Binary</c>.</p>
+ <p>Calculate the Adler-32 checksum for <c><anno>Data</anno></c>.</p>
</desc>
</func>
<func>
- <name>adler32(Z, PrevAdler, Binary) -> Checksum</name>
+ <name name="adler32" arity="3"/>
<fsummary>Calculate the adler checksum</fsummary>
- <type>
- <v>Z = zstream()</v>
- <v>PrevAdler = integer()</v>
- <v>Binary = binary()</v>
- <v>Checksum = integer()</v>
- </type>
- <desc>
- <p>Update a running Adler-32 checksum for <c>Binary</c>.
- If <c>Binary</c> is the empty binary, this function returns
+ <desc>
+ <p>Update a running Adler-32 checksum for <c><anno>Data</anno></c>.
+ If <c><anno>Data</anno></c> is the empty binary or the empty iolist, this function returns
the required initial value for the checksum.</p>
<pre>
-Crc = lists:foldl(fun(Bin,Crc0) ->
- zlib:adler32(Z, Crc0, Bin),
- end, zlib:adler32(Z,&lt;&lt; &gt;&gt;), Bins)</pre>
+Crc = lists:foldl(fun(Data,Crc0) ->
+ zlib:adler32(Z, Crc0, Data),
+ end, zlib:adler32(Z,&lt;&lt; &gt;&gt;), Datas)</pre>
</desc>
</func>
<func>
- <name>adler32_combine(Z, Adler1, Adler2, Size2) -> Adler </name>
+ <name name="adler32_combine" arity="4"/>
<fsummary>Combine two Adler-32 checksums</fsummary>
- <type>
- <v>Z = zstream()</v>
- <v>Adler = integer()</v>
- <v>Adler1 = integer()</v>
- <v>Adler2 = integer()</v>
- <v>Size2 = integer()</v>
- </type>
- <desc>
- <p>Combine two Adler-32 checksums into one. For two binaries,
- <c>Bin1</c> and <c>Bin2</c> with sizes of <c>Size1</c> and
- <c>Size2</c>, with Adler-32 checksums <c>Adler1</c> and
- <c>Adler2</c>. <c>adler32_combine/4</c> returns the <c>Adler</c>
- checksum of <c>&lt;&lt;Bin1/binary,Bin2/binary&gt;&gt;</c>, requiring
- only <c>Adler1</c>, <c>Adler2</c>, and <c>Size2</c>.
+ <desc>
+ <p>Combine two Adler-32 checksums into one. For two binaries or iolists,
+ <c>Data1</c> and <c>Data2</c> with sizes of <c>Size1</c> and
+ <c><anno>Size2</anno></c>, with Adler-32 checksums <c><anno>Adler1</anno></c> and
+ <c><anno>Adler2</anno></c>. <c>adler32_combine/4</c> returns the <c><anno>Adler</anno></c>
+ checksum of <c>[Data1,Data2]</c>, requiring
+ only <c><anno>Adler1</anno></c>, <c><anno>Adler2</anno></c>, and <c><anno>Size2</anno></c>.
</p>
</desc>
</func>
<func>
- <name>compress(Binary) -> Compressed </name>
- <fsummary>Compress a binary with standard zlib functionality</fsummary>
- <type>
- <v>Binary = Compressed = binary()</v>
- </type>
+ <name name="compress" arity="1"/>
+ <fsummary>Compress data with standard zlib functionality</fsummary>
<desc>
- <p>Compress a binary (with zlib headers and checksum).</p>
+ <p>Compress data (with zlib headers and checksum).</p>
</desc>
</func>
<func>
- <name>uncompress(Binary) -> Decompressed</name>
- <fsummary>Uncompress a binary with standard zlib functionality</fsummary>
- <type>
- <v>Binary = Decompressed = binary()</v>
- </type>
+ <name name="uncompress" arity="1"/>
+ <fsummary>Uncompress data with standard zlib functionality</fsummary>
<desc>
- <p>Uncompress a binary (with zlib headers and checksum).</p>
+ <p>Uncompress data (with zlib headers and checksum).</p>
</desc>
</func>
<func>
- <name>zip(Binary) -> Compressed</name>
- <fsummary>Compress a binary without the zlib headers</fsummary>
- <type>
- <v>Binary = Compressed = binary()</v>
- </type>
+ <name name="zip" arity="1"/>
+ <fsummary>Compress data without the zlib headers</fsummary>
<desc>
- <p>Compress a binary (without zlib headers and checksum).</p>
+ <p>Compress data (without zlib headers and checksum).</p>
</desc>
</func>
<func>
- <name>unzip(Binary) -> Decompressed</name>
- <fsummary>Uncompress a binary without the zlib headers</fsummary>
- <type>
- <v>Binary = Decompressed = binary()</v>
- </type>
+ <name name="unzip" arity="1"/>
+ <fsummary>Uncompress data without the zlib headers</fsummary>
<desc>
- <p>Uncompress a binary (without zlib headers and checksum).</p>
+ <p>Uncompress data (without zlib headers and checksum).</p>
</desc>
</func>
<func>
- <name>gzip(Data) -> Compressed</name>
- <fsummary>Compress a binary with gz header</fsummary>
- <type>
- <v>Binary = Compressed = binary()</v>
- </type>
+ <name name="gzip" arity="1"/>
+ <fsummary>Compress data with gz header</fsummary>
<desc>
- <p>Compress a binary (with gz headers and checksum).</p>
+ <p>Compress data (with gz headers and checksum).</p>
</desc>
</func>
<func>
- <name>gunzip(Bin) -> Decompressed</name>
- <fsummary>Uncompress a binary with gz header</fsummary>
- <type>
- <v>Binary = Decompressed = binary()</v>
- </type>
+ <name name="gunzip" arity="1"/>
+ <fsummary>Uncompress data with gz header</fsummary>
<desc>
- <p>Uncompress a binary (with gz headers and checksum).</p>
+ <p>Uncompress data (with gz headers and checksum).</p>
</desc>
</func>
</funcs>
generated by cgit v1.2.3 (git 2.25.1) at 2024-11-11 23:34:41 +0000