From 84adefa331c4159d432d22840663c38f155cd4c1 Mon Sep 17 00:00:00 2001 From: Erlang/OTP Date: Fri, 20 Nov 2009 14:54:40 +0000 Subject: The R13B03 release. --- erts/doc/src/Makefile | 153 + erts/doc/src/absform.xml | 444 +++ erts/doc/src/alt_dist.xml | 1099 ++++++ erts/doc/src/book.xml | 49 + erts/doc/src/crash_dump.xml | 518 +++ erts/doc/src/driver.xml | 812 ++++ erts/doc/src/driver_entry.xml | 453 +++ erts/doc/src/epmd.xml | 120 + erts/doc/src/erl.xml | 928 +++++ erts/doc/src/erl_dist_protocol.xml | 802 ++++ erts/doc/src/erl_driver.xml | 2465 ++++++++++++ erts/doc/src/erl_ext_dist.xml | 1014 +++++ erts/doc/src/erl_ext_fig.gif | Bin 0 -> 3834 bytes erts/doc/src/erl_ext_fig.ps | 153 + erts/doc/src/erl_fix_alloc.fig | 104 + erts/doc/src/erl_fix_alloc.gif | Bin 0 -> 5638 bytes erts/doc/src/erl_fix_alloc.ps | 646 +++ erts/doc/src/erl_nif.xml | 351 ++ erts/doc/src/erl_prim_loader.xml | 251 ++ erts/doc/src/erl_set_memory_block.xml | 172 + erts/doc/src/erlang.xml | 6920 +++++++++++++++++++++++++++++++++ erts/doc/src/erlc.xml | 256 ++ erts/doc/src/erlsrv.xml | 405 ++ erts/doc/src/erts_alloc.xml | 554 +++ erts/doc/src/escript.xml | 232 ++ erts/doc/src/fascicules.xml | 18 + erts/doc/src/inet_cfg.xml | 397 ++ erts/doc/src/init.xml | 384 ++ erts/doc/src/make.dep | 32 + erts/doc/src/match_spec.xml | 564 +++ erts/doc/src/notes.xml | 5439 ++++++++++++++++++++++++++ erts/doc/src/notes_history.xml | 503 +++ erts/doc/src/part.xml | 44 + erts/doc/src/part_notes.xml | 37 + erts/doc/src/part_notes_history.xml | 35 + erts/doc/src/ref_man.xml | 60 + erts/doc/src/run_erl.xml | 155 + erts/doc/src/start.xml | 64 + erts/doc/src/start_erl.xml | 126 + erts/doc/src/tty.xml | 137 + erts/doc/src/werl.xml | 88 + erts/doc/src/zlib.xml | 606 +++ 42 files changed, 27590 insertions(+) create mode 100644 erts/doc/src/Makefile create mode 100644 erts/doc/src/absform.xml create mode 100644 erts/doc/src/alt_dist.xml create mode 100644 erts/doc/src/book.xml create mode 100644 erts/doc/src/crash_dump.xml create mode 100644 erts/doc/src/driver.xml create mode 100644 erts/doc/src/driver_entry.xml create mode 100644 erts/doc/src/epmd.xml create mode 100644 erts/doc/src/erl.xml create mode 100644 erts/doc/src/erl_dist_protocol.xml create mode 100644 erts/doc/src/erl_driver.xml create mode 100644 erts/doc/src/erl_ext_dist.xml create mode 100755 erts/doc/src/erl_ext_fig.gif create mode 100644 erts/doc/src/erl_ext_fig.ps create mode 100644 erts/doc/src/erl_fix_alloc.fig create mode 100644 erts/doc/src/erl_fix_alloc.gif create mode 100644 erts/doc/src/erl_fix_alloc.ps create mode 100644 erts/doc/src/erl_nif.xml create mode 100644 erts/doc/src/erl_prim_loader.xml create mode 100644 erts/doc/src/erl_set_memory_block.xml create mode 100644 erts/doc/src/erlang.xml create mode 100644 erts/doc/src/erlc.xml create mode 100644 erts/doc/src/erlsrv.xml create mode 100644 erts/doc/src/erts_alloc.xml create mode 100644 erts/doc/src/escript.xml create mode 100644 erts/doc/src/fascicules.xml create mode 100644 erts/doc/src/inet_cfg.xml create mode 100644 erts/doc/src/init.xml create mode 100644 erts/doc/src/make.dep create mode 100644 erts/doc/src/match_spec.xml create mode 100644 erts/doc/src/notes.xml create mode 100644 erts/doc/src/notes_history.xml create mode 100644 erts/doc/src/part.xml create mode 100644 erts/doc/src/part_notes.xml create mode 100644 erts/doc/src/part_notes_history.xml create mode 100644 erts/doc/src/ref_man.xml create mode 100644 erts/doc/src/run_erl.xml create mode 100644 erts/doc/src/start.xml create mode 100644 erts/doc/src/start_erl.xml create mode 100644 erts/doc/src/tty.xml create mode 100644 erts/doc/src/werl.xml create mode 100644 erts/doc/src/zlib.xml (limited to 'erts/doc/src') diff --git a/erts/doc/src/Makefile b/erts/doc/src/Makefile new file mode 100644 index 0000000000..3dfefa2001 --- /dev/null +++ b/erts/doc/src/Makefile @@ -0,0 +1,153 @@ +# +# %CopyrightBegin% +# +# Copyright Ericsson AB 1997-2009. 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% +# +include $(ERL_TOP)/make/target.mk +include $(ERL_TOP)/make/$(TARGET)/otp.mk + +# ---------------------------------------------------- +# Application version +# ---------------------------------------------------- +include ../../vsn.mk +APPLICATION=erts +# ---------------------------------------------------- +# Release directory specification +# ---------------------------------------------------- +RELSYSDIR = $(RELEASE_PATH)/$(APPLICATION)-$(VSN) + +# ---------------------------------------------------- +# Target Specs +# ---------------------------------------------------- +XML_APPLICATION_FILES = ref_man.xml +XML_REF1_FILES = epmd.xml \ + erl.xml \ + erlc.xml \ + escript.xml \ + werl.xml \ + erlsrv.xml \ + start_erl.xml \ + run_erl.xml \ + start.xml + +XML_REF3_FILES = \ + driver_entry.xml \ + erl_set_memory_block.xml \ + erl_driver.xml \ + erl_prim_loader.xml \ + erlang.xml \ + erts_alloc.xml \ + init.xml \ + zlib.xml + +XML_PART_FILES = \ + part.xml \ + part_notes.xml \ + part_notes_history.xml + +XML_CHAPTER_FILES = \ + tty.xml \ + match_spec.xml \ + crash_dump.xml \ + alt_dist.xml \ + driver.xml \ + absform.xml \ + inet_cfg.xml \ + erl_ext_dist.xml \ + erl_dist_protocol.xml \ + notes.xml \ + notes_history.xml + +TOPDOCDIR=../../../doc + +BOOK_FILES = book.xml + +GIF_FILES = \ + erl_ext_fig.gif + +XML_FILES = \ + $(BOOK_FILES) $(XML_CHAPTER_FILES) \ + $(XML_PART_FILES) $(XML_REF3_FILES) $(XML_REF1_FILES) $(XML_APPLICATION_FILES) + +# ---------------------------------------------------- + +HTML_FILES = $(XML_APPLICATION_FILES:%.xml=$(HTMLDIR)/%.html) \ + $(XML_PART_FILES:%.xml=$(HTMLDIR)/%.html) + +INFO_FILE = ../../info +INFO_FILE_SRC = ../../info.src + +MAN1_FILES = $(XML_REF1_FILES:%.xml=$(MAN1DIR)/%.1) +MAN3_FILES = $(XML_REF3_FILES:%.xml=$(MAN3DIR)/%.3) + +HTML_REF_MAN_FILE = $(HTMLDIR)/index.html + +TOP_PDF_FILE = $(PDFDIR)/$(APPLICATION)-$(VSN).pdf + +# ---------------------------------------------------- +# FLAGS +# ---------------------------------------------------- +XML_FLAGS += + +# ---------------------------------------------------- +# Targets +# ---------------------------------------------------- +$(HTMLDIR)/%.gif: %.gif + $(INSTALL_DATA) $< $@ + +docs: pdf html man $(INFO_FILE) + +$(TOP_PDF_FILE): $(XML_FILES) + +pdf: $(TOP_PDF_FILE) + +html: gifs $(HTML_REF_MAN_FILE) + +man: $(MAN1_FILES) $(MAN3_FILES) + +gifs: $(GIF_FILES:%=$(HTMLDIR)/%) + +$(INFO_FILE): $(INFO_FILE_SRC) ../../vsn.mk + sed -e 's;%RELEASE%;$(SYSTEM_VSN);' $(INFO_FILE_SRC) > $(INFO_FILE) + + +debug opt: + +clean: + rm -rf $(HTMLDIR)/* + rm -f $(MAN1DIR)/* + rm -f $(MAN3DIR)/* + rm -f $(TOP_PDF_FILE) $(TOP_PDF_FILE:%.pdf=%.fo) + rm -f errs core *~ + +# ---------------------------------------------------- +# Release Target +# ---------------------------------------------------- +include $(ERL_TOP)/make/otp_release_targets.mk + +release_docs_spec: docs + $(INSTALL_DIR) $(RELSYSDIR)/doc/pdf + $(INSTALL_DATA) $(TOP_PDF_FILE) $(RELSYSDIR)/doc/pdf + $(INSTALL_DIR) $(RELSYSDIR)/doc/html + $(INSTALL_DATA) $(HTMLDIR)/* \ + $(RELSYSDIR)/doc/html + $(INSTALL_DATA) $(INFO_FILE) $(RELSYSDIR) + $(INSTALL_DIR) $(RELEASE_PATH)/man/man3 + $(INSTALL_DATA) $(MAN3DIR)/* $(RELEASE_PATH)/man/man3 + $(INSTALL_DIR) $(RELEASE_PATH)/man/man1 + $(INSTALL_DATA) $(MAN1_FILES) $(RELEASE_PATH)/man/man1 + +release_spec: diff --git a/erts/doc/src/absform.xml b/erts/doc/src/absform.xml new file mode 100644 index 0000000000..4c84412dd6 --- /dev/null +++ b/erts/doc/src/absform.xml @@ -0,0 +1,444 @@ + + + + +
+ + 20012009 + Ericsson AB. 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. + + + + The Abstract Format + Arndt Jonasson + Kenneth Lundin + 1 + Jultomten + + 00-12-01 + A + absform.xml +
+

+

This document describes the standard representation of parse trees for Erlang + programs as Erlang terms. This representation is known as the abstract format. + Functions dealing with such parse trees are + and functions in the modules + , + , + , + , + , + and + . + They are also used as input and output for parse transforms (see the module + ).

+

We use the function to denote the mapping from an Erlang source + construct to its abstract format representation , and write + . +

+

The word below represents an integer, and denotes the + number of the line in the source file where the construction occurred. + Several instances of in the same construction may denote + different lines.

+

Since operators are not terms in their own right, when operators are + mentioned below, the representation of an operator should be taken to + be the atom with a printname consisting of the same characters as the + operator. +

+ +
+ Module declarations and forms +

A module declaration consists of a sequence of forms that are either + function declarations or attributes.

+ + If D is a module declaration consisting of the forms + , ..., , then + Rep(D) = . + If F is an attribute , then + Rep(F) = . + If F is an attribute , then + Rep(F) = . + If F is an attribute , then + Rep(F) = . + If F is an attribute , then + Rep(F) = . + If F is an attribute , then + Rep(F) = . + If F is a record declaration , then + Rep(F) = + . For Rep(V), see below. + If F is a wild attribute , then + Rep(F) = . +

+ If F is a function declaration , + where each is a function clause with a + pattern sequence of the same length , then + Rep(F) = . + + +
+ Record fields +

Each field in a record declaration may have an optional + explicit default initializer expression

+ + If V is , then + Rep(V) = . + If V is , then + Rep(V) = . + +
+ +
+ Representation of parse errors and end of file +

In addition to the representations of forms, the list that represents + a module declaration (as returned by functions in and + ) may contain tuples and , denoting + syntactically incorrect forms and warnings, and , denoting an end + of stream encountered before a complete form had been parsed.

+
+
+ +
+ Atomic literals +

There are five kinds of atomic literals, which are represented in the + same way in patterns, expressions and guards:

+ + If L is an integer or character literal, then + Rep(L) = . + If L is a float literal, then + Rep(L) = . + If L is a string literal consisting of the characters + , ..., , then + Rep(L) = . + If L is an atom literal, then + Rep(L) = . + +

Note that negative integer and float literals do not occur as such; they are + parsed as an application of the unary negation operator.

+
+ +
+ Patterns +

If is a sequence of patterns , then + Rep(Ps) = . Such sequences occur as the + list of arguments to a function or fun.

+

Individual patterns are represented as follows:

+ + If P is an atomic literal L, then Rep(P) = Rep(L). + If P is a compound pattern , then + Rep(P) = . + If P is a variable pattern , then + Rep(P) = , + where A is an atom with a printname consisting of the same characters as + . + If P is a universal pattern , then + Rep(P) = . + If P is a tuple pattern , then + Rep(P) = . + If P is a nil pattern , then + Rep(P) = . + If P is a cons pattern , then + Rep(P) = . + If E is a binary pattern >]]>, then + Rep(E) = . + For Rep(TSL), see below. + An omitted is represented by . An omitted + (type specifier list) is represented by . + If P is , where is a binary operator (this + is either an occurrence of applied to a literal string or character + list, or an occurrence of an expression that can be evaluated to a number + at compile time), + then Rep(P) = . + If P is , where is a unary operator (this is an + occurrence of an expression that can be evaluated to a number at compile + time), then Rep(P) = . + If P is a record pattern , + then Rep(P) = + . + If P is , then + Rep(P) = . + If P is , then + Rep(P) = , + i.e., patterns cannot be distinguished from their bodies. + +

Note that every pattern has the same source form as some expression, and is + represented the same way as the corresponding expression.

+
+ +
+ Expressions +

A body B is a sequence of expressions , and + Rep(B) = .

+

An expression E is one of the following alternatives:

+ + If P is an atomic literal , then + Rep(P) = Rep(L). + If E is , then + Rep(E) = . + If E is a variable , then + Rep(E) = , + where is an atom with a printname consisting of the same + characters as . + If E is a tuple skeleton , then + Rep(E) = . + If E is , then + Rep(E) = . + If E is a cons skeleton , then + Rep(E) = . + If E is a binary constructor >]]>, then + Rep(E) = . + For Rep(TSL), see below. + An omitted is represented by . An omitted + (type specifier list) is represented by . + If E is , where is a binary operator, + then Rep(E) = . + If E is , where is a unary operator, then + Rep(E) = . + If E is , then + Rep(E) = + . + If E is , then + Rep(E) = + . + If E is , then + Rep(E) = . + If E is , then + Rep(E) = . + If E is , then + Rep(E) = . + If E is , then + Rep(E) = . + If E is , then + Rep(E) = + . + If E is a list comprehension , + where each is a generator or a filter, then + Rep(E) = . For Rep(W), see + below. + If E is a binary comprehension >]]>, + where each is a generator or a filter, then + Rep(E) = . For Rep(W), see + below. + If E is , where is a body, then + Rep(E) = . + If E is , + where each is an if clause then + Rep(E) = + . + If E is , + where is an expression and each is a + case clause then + Rep(E) = + . + If E is , + where is a body and each is a catch clause then + Rep(E) = + . + If E is , + where is a body, + each is a case clause and + each is a catch clause then + Rep(E) = + . + If E is , + where and are bodies then + Rep(E) = + . + If E is , + where and are a bodies and + each is a case clause then + Rep(E) = + . + If E is , + where and are bodies and + each is a catch clause then + Rep(E) = + . + If E is , + where and are a bodies, + each is a case clause and + each is a catch clause then + Rep(E) = + . + If E is , + where each is a case clause then + Rep(E) = + . + If E is B_t end]]>, + where each is a case clause, + is an expression and is a body, then + Rep(E) = + . + If E is , then + Rep(E) = . + If E is , then + Rep(E) = . + If E is + where each is a function clause then Rep(E) = + . + If E is , + where each is a generator or a filter, then + Rep(E) = . + For Rep(W), see below. + If E is , a Mnesia record access + inside a query, then + Rep(E) = . + If E is , then + Rep(E) = , + i.e., parenthesized expressions cannot be distinguished from their bodies. + + +
+ Generators and filters +

When W is a generator or a filter (in the body of a list or binary comprehension), then:

+ + If W is a generator , where is a pattern and + is an expression, then + Rep(W) = . + If W is a generator , where is a pattern and + is an expression, then + Rep(W) = . + If W is a filter , which is an expression, then + Rep(W) = . + +
+ +
+ Binary element type specifiers +

A type specifier list TSL for a binary element is a sequence of type + specifiers . + Rep(TSL) = .

+

When TS is a type specifier for a binary element, then:

+ + If TS is an atom , Rep(TS) = . + If TS is a couple where is an atom and + is an integer, Rep(TS) = . + +
+
+ +
+ Clauses +

There are function clauses, if clauses, case clauses + and catch clauses.

+

A clause is one of the following alternatives:

+ + If C is a function clause B]]> + where is a pattern sequence and is a body, then + Rep(C) = . + If C is a function clause B]]> + where is a pattern sequence, + is a guard sequence and is a body, then + Rep(C) = . + If C is an if clause B]]> + where is a guard sequence and is a body, then + Rep(C) = . + If C is a case clause B]]> + where is a pattern and is a body, then + Rep(C) = . + If C is a case clause B]]> + where is a pattern, + is a guard sequence and is a body, then + Rep(C) = . + If C is a catch clause B]]> + where is a pattern and is a body, then + Rep(C) = . + If C is a catch clause B]]> + where is an atomic literal or a variable pattern, + is a pattern and is a body, then + Rep(C) = . + If C is a catch clause B]]> + where is a pattern, is a guard sequence + and is a body, then + Rep(C) = . + If C is a catch clause B]]> + where is an atomic literal or a variable pattern, + is a pattern, is a guard sequence + and is a body, then + Rep(C) = . + +
+ +
+ Guards +

A guard sequence Gs is a sequence of guards , and + Rep(Gs) = . If the guard sequence is + empty, Rep(Gs) = .

+

A guard G is a nonempty sequence of guard tests , and + Rep(G) = .

+

A guard test is one of the following alternatives:

+ + If Gt is an atomic literal L, then Rep(Gt) = Rep(L). + If Gt is a variable pattern , then + Rep(Gt) = , + where A is an atom with a printname consisting of the same characters as + . + If Gt is a tuple skeleton , then + Rep(Gt) = . + If Gt is , then + Rep(Gt) = . + If Gt is a cons skeleton , then + Rep(Gt) = . + If Gt is a binary constructor >]]>, then + Rep(Gt) = . + For Rep(TSL), see above. + An omitted is represented by . An omitted + (type specifier list) is represented by . + If Gt is , where + is a binary operator, then Rep(Gt) = . + If Gt is , where is a unary operator, then + Rep(Gt) = . + If Gt is , then + Rep(E) = + . + If Gt is , then + Rep(Gt) = . + If Gt is , then + Rep(Gt) = . + If Gt is , where is an atom, then + Rep(Gt) = . + If Gt is , where is + the atom and is an atom or an operator, then + Rep(Gt) = . + If Gt is , where is + the atom and is an atom or an operator, then + Rep(Gt) = . + If Gt is , then + Rep(Gt) = , + i.e., parenthesized guard tests cannot be distinguished from their bodies. + +

Note that every guard test has the same source form as some expression, + and is represented the same way as the corresponding expression.

+
+ +
+ The abstract format after preprocessing +

The compilation option can be given to the + compiler to have the abstract code stored in + the chunk in the BEAM file + (for debugging purposes).

+

In OTP R9C and later, the chunk will + contain

+

+

where is the abstract code as described + in this document.

+

In releases of OTP prior to R9C, the abstract code after some more + processing was stored in the BEAM file. The first element of the + tuple would be either (R7B) or + (R8B).

+
+ + diff --git a/erts/doc/src/alt_dist.xml b/erts/doc/src/alt_dist.xml new file mode 100644 index 0000000000..9a68b3cf40 --- /dev/null +++ b/erts/doc/src/alt_dist.xml @@ -0,0 +1,1099 @@ + + + + +
+ + 20002009 + Ericsson AB. 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. + + + + How to implement an alternative carrier for the Erlang distribution + Patrik Nyblom + + + + + 2000-10-17 + PA2 + alt_dist.xml +
+

This document describes how one can implement ones own carrier + protocol for the Erlang distribution. The distribution is normally + carried by the TCP/IP protocol. What's explained here is the method for + replacing TCP/IP with another protocol.

+

The document is a step by step explanation of the example + application (seated in the kernel applications directory). + The application implements distribution over Unix domain + sockets and is written for the Sun Solaris 2 operating environment. The + mechanisms are however general and applies to any operating system Erlang + runs on. The reason the C code is not made portable, is simply readability.

+

This document was written a long time ago. Most of it is still + valid, but some things have changed since it was first written. + Most notably the driver interface. There have been some updates + to the documentation of the driver presented in this documentation, + but more could be done and are planned for the future. The + reader is encouraged to also read the + erl_driver, and the + driver_entry documentation. +

+ +
+ Introduction +

To implement a new carrier for the Erlang distribution, one must first + make the protocol available to the Erlang machine, which involves writing + an Erlang driver. There is no way one can use a port program, + there has to + be an Erlang driver. Erlang drivers can either be statically + linked + to the emulator, which can be an alternative when using the open source + distribution of Erlang, or dynamically loaded into the Erlang machines + address space, which is the only alternative if a precompiled version of + Erlang is to be used.

+

Writing an Erlang driver is by no means easy. The driver is written + as a couple of call-back functions called by the Erlang emulator when + data is sent to the driver or the driver has any data available on a file + descriptor. As the driver call-back routines execute in the main + thread of the Erlang machine, the call-back functions can perform + no blocking activity whatsoever. The call-backs should only set up + file descriptors for waiting and/or read/write available data. All + I/O has to be non blocking. Driver call-backs are however executed + in sequence, why a global state can safely be updated within the + routines.

+

When the driver is implemented, one would preferably write an + Erlang interface for the driver to be able to test the + functionality of the driver separately. This interface can then + be used by the distribution module which will cover the details of + the protocol from the . The easiest path is to + mimic the and interfaces, but a lot of + functionality in those modules need not be implemented. In the + example application, only a few of the usual interfaces are + implemented, and they are much simplified.

+

When the protocol is available to Erlang through a driver and an + Erlang interface module, a distribution module can be + written. The distribution module is a module with well defined + call-backs, much like a (there is no compiler support + for checking the call-backs though). The details of finding other + nodes (i.e. talking to epmd or something similar), creating a + listen port (or similar), connecting to other nodes and performing + the handshakes/cookie verification are all implemented by this + module. There is however a utility module, , that + will do most of the hard work of handling handshakes, cookies, + timers and ticking. Using makes implementing a + distribution module much easier and that's what we are doing in + the example application.

+

The last step is to create boot scripts to make the protocol + implementation available at boot time. The implementation can be + debugged by starting the distribution when all of the system is + running, but in a real system the distribution should start very + early, why a boot-script and some command line parameters are + necessary. This last step also implies that the Erlang code in the + interface and distribution modules is written in such a way that + it can be run in the startup phase. Most notably there can be no + calls to the module or to any modules not + loaded at boot-time (i.e. only , and the + application itself can be used).

+
+ +
+ The driver +

Although Erlang drivers in general may be beyond the scope of this + document, a brief introduction seems to be in place.

+ +
+ Drivers in general +

An Erlang driver is a native code module written in C (or + assembler) which serves as an interface for some special operating + system service. This is a general mechanism that is used + throughout the Erlang emulator for all kinds of I/O. An Erlang + driver can be dynamically linked (or loaded) to the Erlang + emulator at runtime by using the Erlang + module. Some of the drivers in OTP are however statically linked + to the runtime system, but that's more an optimization than a + necessity.

+

The driver data-types and the functions available to the driver + writer are defined in the header file (there + is also an deprecated version called , don't use + that one.) seated in Erlang's include directory (and in + $ERL_TOP/erts/emulator/beam in the source code + distribution). Refer to that file for function prototypes etc.

+

When writing a driver to make a communications protocol available + to Erlang, one should know just about everything worth knowing + about that particular protocol. All operation has to be non + blocking and all possible situations should be accounted for in + the driver. A non stable driver will affect and/or crash the + whole Erlang runtime system, which is seldom what's wanted.

+

The emulator calls the driver in the following situations:

+ + When the driver is loaded. This call-back has to have a + special name and will inform the emulator of what call-backs should + be used by returning a pointer to a struct, + which should be properly filled in (see below). + When a port to the driver is opened (by a + call from Erlang). This routine should set up internal data + structures and return an opaque data entity of the type + , which is a data-type large enough to hold a + pointer. The pointer returned by this function will be the first + argument to all other call-backs concerning this particular + port. It is usually called the port handle. The emulator only + stores the handle and does never try to interpret it, why it can + be virtually anything (well anything not larger than a pointer + that is) and can point to anything if it is a pointer. Usually + this pointer will refer to a structure holding information about + the particular port, as i t does in our example. + When an Erlang process sends data to the port. The data will + arrive as a buffer of bytes, the interpretation is not defined, + but is up to the implementor. This call-back returns nothing to the + caller, answers are sent to the caller as messages (using a + routine called available to all + drivers). There is also a way to talk in a synchronous way to + drivers, described below. There can be an additional call-back + function for handling data that is fragmented (sent in a deep + io-list). That interface will get the data in a form suitable for + Unix rather than in a single buffer. There is no + need for a distribution driver to implement such a call-back, so + we wont. + When a file descriptor is signaled for input. This call-back + is called when the emulator detects input on a file descriptor + which the driver has marked for monitoring by using the interface + . The mechanism of driver select makes it + possible to read non blocking from file descriptors by calling + when reading is needed and then do the actual + reading in this call-back (when reading is actually possible). The + typical scenario is that is called when an + Erlang process orders a read operation, and that this routine + sends the answer when data is available on the file descriptor. + When a file descriptor is signaled for output. This call-back + is called in a similar way as the previous, but when writing to a + file descriptor is possible. The usual scenario is that Erlang + orders writing on a file descriptor and that the driver calls + . When the descriptor is ready for output, + this call-back is called an the driver can try to send the + output. There may of course be queuing involved in such + operations, and there are some convenient queue routines available + to the driver writer to use in such situations. + When a port is closed, either by an Erlang process or by the + driver calling one of the routines. This + routine should clean up everything connected to one particular + port. Note that when other call-backs call a + routine, this routine will be + immediately called and the call-back routine issuing the error can + make no more use of the data structures for the port, as this + routine surely has freed all associated data and closed all file + descriptors. If the queue utility available to driver writes is + used, this routine will however not be called until the + queue is empty. + When an Erlang process calls erlang:port_control/3, + which is a synchronous interface to drivers. The control interface + is used to set driver options, change states of ports etc. We'll + use this interface quite a lot in our example. + When a timer expires. The driver can set timers with the + function . When such timers expire, a + specific call-back function is called. We will not use timers in + our example. + When the whole driver is unloaded. Every resource allocated + by the driver should be freed. + +
+ +
+ The distribution driver's data structures +

The driver used for Erlang distribution should implement a + reliable, order maintaining, variable length packet oriented + protocol. All error correction, re-sending and such need to be + implemented in the driver or by the underlying communications + protocol. If the protocol is stream oriented (as is the case with + both TCP/IP and our streamed Unix domain sockets), some mechanism + for packaging is needed. We will use the simple method of having a + header of four bytes containing the length of the package in a big + endian 32 bit integer (as Unix domain sockets only can be used + between processes on the same machine, we actually don't need to + code the integer in some special endianess, but I'll do it anyway + because in most situation you do need to do it. Unix domain + sockets are reliable and order maintaining, so we don't need to + implement resends and such in our driver.

+

Lets start writing our example Unix domain sockets driver by + declaring prototypes and filling in a static ErlDrvEntry + structure.

+ +( 2) #include +( 3) #include +( 4) #include +( 5) #include +( 6) #include +( 7) #include +( 8) #include +( 9) #include +(10) #include + +(11) #define HAVE_UIO_H +(12) #include "erl_driver.h" + +(13) /* +(14) ** Interface routines +(15) */ +(16) static ErlDrvData uds_start(ErlDrvPort port, char *buff); +(17) static void uds_stop(ErlDrvData handle); +(18) static void uds_command(ErlDrvData handle, char *buff, int bufflen); +(19) static void uds_input(ErlDrvData handle, ErlDrvEvent event); +(20) static void uds_output(ErlDrvData handle, ErlDrvEvent event); +(21) static void uds_finish(void); +(22) static int uds_control(ErlDrvData handle, unsigned int command, +(23) char* buf, int count, char** res, int res_size); + +(24) /* The driver entry */ +(25) static ErlDrvEntry uds_driver_entry = { +(26) NULL, /* init, N/A */ +(27) uds_start, /* start, called when port is opened */ +(28) uds_stop, /* stop, called when port is closed */ +(29) uds_command, /* output, called when erlang has sent */ +(30) uds_input, /* ready_input, called when input +(31) descriptor ready */ +(32) uds_output, /* ready_output, called when output +(33) descriptor ready */ +(34) "uds_drv", /* char *driver_name, the argument +(35) to open_port */ +(36) uds_finish, /* finish, called when unloaded */ +(37) NULL, /* void * that is not used (BC) */ +(38) uds_control, /* control, port_control callback */ +(39) NULL, /* timeout, called on timeouts */ +(40) NULL, /* outputv, vector output interface */ +(41) NULL, /* ready_async callback */ +(42) NULL, /* flush callback */ +(43) NULL, /* call callback */ +(44) NULL, /* event callback */ +(45) ERL_DRV_EXTENDED_MARKER, /* Extended driver interface marker */ +(46) ERL_DRV_EXTENDED_MAJOR_VERSION, /* Major version number */ +(47) ERL_DRV_EXTENDED_MINOR_VERSION, /* Minor version number */ +(48) ERL_DRV_FLAG_SOFT_BUSY, /* Driver flags. Soft busy flag is +(49) required for distribution drivers */ +(50) NULL, /* Reserved for internal use */ +(51) NULL, /* process_exit callback */ +(52) NULL /* stop_select callback */ +(53) };]]> +

On line 1 to 10 we have included the OS headers needed for our + driver. As this driver is written for Solaris, we know that the + header exists, why we can define the preprocessor + variable before we include + at line 12. The definition of will make the + I/O vectors used in Erlang's driver queues to correspond to the + operating systems ditto, which is very convenient.

+

The different call-back functions are declared ("forward + declarations") on line 16 to 23.

+

The driver structure is similar for statically linked in + drivers and dynamically loaded. However some of the fields + should be left empty (i.e. initialized to NULL) in the + different types of drivers. The first field (the + function pointer) is always left blank in a dynamically loaded + driver, which can be seen on line 26. The NULL on line 37 + should always be there, the field is no longer used and is + retained for backward compatibility. We use no timers in this + driver, why no call-back for timers is needed. The outputv field + (line 40) can be used to implement an interface similar to + Unix for output. The Erlang runtime + system could previously not use outputv for the + distribution, but since erts version 5.7.2 it can. + Since this driver was written before erts version 5.7.2 it does + not use the outputv callback. Using the outputv + callback is preferred since it reduces copying of data. (We + will however use scatter/gather I/O internally in the driver).

+

As of erts version 5.5.3 the driver interface was extended with + version control and the possibility to pass capability information. + Capability flags are present at line 48. As of erts version 5.7.4 + the + ERL_DRV_FLAG_SOFT_BUSY + flag is required for drivers that are to be used by the distribution. + The soft busy flag implies that the driver is capable of handling + calls to the output and outputv callbacks even though + it has marked itself as busy. This has always been a requirement + on drivers used by the distribution, but there have previously not + been any capability information available about this. For more + information see + set_busy_port()). +

+

This driver was written before the runtime system had SMP support. + The driver will still function in the runtime system with SMP support, + but performance will suffer from lock contention on the driver lock + used for the driver. This can be alleviated by reviewing and perhaps + rewriting the code so that each instance of the driver safely can + execute in parallel. When instances safely can execute in parallel it + is safe to enable instance specific locking on the driver. This is done + by passing + ERL_DRV_FLAG_USE_PORT_LOCKING + as a driver flag. This is left as an exercise for the reader.

+

Our defined call-backs thus are:

+ + uds_start, which shall initiate data for a port. We wont + create any actual sockets here, just initialize data structures. + uds_stop, the function called when a port is closed. + uds_command, which will handle messages from Erlang. The + messages can either be plain data to be sent or more subtle + instructions to the driver. We will use this function mostly for + data pumping. + uds_input, this is the call-back which is called when we have + something to read from a socket. + uds_output, this is the function called when we can write to a + socket. + uds_finish, which is called when the driver is unloaded. A + distribution driver will actually (or hopefully) never be unloaded, + but we include this for completeness. Being able to clean up after + oneself is always a good thing. + uds_control, the erlang:port_control/2 call-back, which + will be used a lot in this implementation. + +

The ports implemented by this driver will operate in two major + modes, which i will call the command and data + modes. In command mode, only passive reading and writing (like + gen_tcp:recv/gen_tcp:send) can be + done, and this is the mode the port will be in during the + distribution handshake. When the connection is up, the port will + be switched to data mode and all data will be immediately read and + passed further to the Erlang emulator. In data mode, no data + arriving to the uds_command will be interpreted, but just packaged + and sent out on the socket. The uds_control call-back will do the + switching between those two modes.

+

While the informs different subsystems that the + connection is coming up, the port should accept data to send, but + not receive any data, to avoid that data arrives from another node + before every kernel subsystem is prepared to handle it. We have a + third mode for this intermediate stage, lets call it the + intermediate mode.

+

Lets define an enum for the different types of ports we have:

+ +

Lets look at the different types:

+ + portTypeUnknown - The type a port has when it's opened, but + not actually bound to any file descriptor. + portTypeListener - A port that is connected to a listen + socket. This port will not do especially much, there will be no data + pumping done on this socket, but there will be read data available + when one is trying to do an accept on the port. + portTypeAcceptor - This is a port that is to represent the + result of an accept operation. It is created when one wants to + accept from a listen socket, and it will be converted to a + portTypeCommand when the accept succeeds. + portTypeConnector - Very similar to portTypeAcceptor, an + intermediate stage between the request for a connect operation and + that the socket is really connected to an accepting ditto in the + other end. As soon as the sockets are connected, the port will + switch type to portTypeCommand. + portTypeCommand - A connected socket (or accepted socket if + you want) that is in the command mode mentioned earlier. + portTypeIntermediate - The intermediate stage for a connected + socket. There should be no processing of input for this socket. + portTypeData - The mode where data is pumped through the port + and the uds_command routine will regard every call as a call where + sending is wanted. In this mode all input available will be read and + sent to Erlang as soon as it arrives on the socket, much like in the + active mode of a socket. + +

Now lets look at the state we'll need for our ports. One can note + that not all fields are used for all types of ports and that one + could save some space by using unions, but that would clutter the + code with multiple indirections, so i simply use one struct for + all types of ports, for readability.

+ +

This structure is used for all types of ports although some + fields are useless for some types. The least memory consuming + solution would be to arrange this structure as a union of + structures, but the multiple indirections in the code to + access a field in such a structure will clutter the code to + much for an example.

+

Let's look at the fields in our structure:

+ + fd - The file descriptor of the socket associated with the + port. + port - The port identifier for the port which this structure + corresponds to. It is needed for most + calls from the driver back to the emulator. + +

lockfd - If the socket is a listen socket, we use a separate + (regular) file for two purposes:

+ + We want a locking mechanism that gives no race + conditions, so that we can be sure of if another Erlang + node uses the listen socket name we require or if the + file is only left there from a previous (crashed) + session. + +

We store the creation serial number in the + file. The creation is a number that should + change between different instances of different Erlang + emulators with the same name, so that process + identifiers from one emulator won't be valid when sent + to a new emulator with the same distribution name. The + creation can be between 0 and 3 (two bits) and is stored + in every process identifier sent to another node.

+

In a system with TCP based distribution, this data is + kept in the Erlang port mapper daemon + (), which is contacted when a distributed + node starts. The lock-file and a convention for the UDS + listen socket's name will remove the need for + when using this distribution module. UDS + is always restricted to one host, why avoiding a port + mapper is easy.

+ + + + creation - The creation number for a listen socket, which is + calculated as (the value found in the lock-file + 1) rem + 4. This creation value is also written back into the + lock-file, so that the next invocation of the emulator will + found our value in the file. + type - The current type/state of the port, which can be one + of the values declared above. + name - The name of the socket file (the path prefix + removed), which allows for deletion () when the + socket is closed. + sent - How many bytes that have been sent over the + socket. This may wrap, but that's no problem for the + distribution, as the only thing that interests the Erlang + distribution is if this value has changed (the Erlang + net_kernel ticker uses this value by calling the + driver to fetch it, which is done through the + erlang:port_control routine). + received - How many bytes that are read (received) from the + socket, used in similar ways as . + partner - A pointer to another port structure, which is + either the listen port from which this port is accepting a + connection or the other way around. The "partner relation" + is always bidirectional. + next - Pointer to next structure in a linked list of all + port structures. This list is used when accepting + connections and when the driver is unloaded. + buffer_size, buffer_pos, header_pos, buffer - data for input + buffering. Refer to the source code (in the kernel/examples + directory) for details about the input buffering. That + certainly goes beyond the scope of this document. + +
+ +
+ Selected parts of the distribution driver implementation +

The distribution drivers implementation is not completely + covered in this text, details about buffering and other things + unrelated to driver writing are not explained. Likewise are + some peculiarities of the UDS protocol not explained in + detail. The chosen protocol is not important.

+

Prototypes for the driver call-back routines can be found in + the header file.

+

The driver initialization routine is (usually) declared with a + macro to make the driver easier to port between different + operating systems (and flavours of systems). This is the only + routine that has to have a well defined name. All other + call-backs are reached through the driver structure. The macro + to use is named and takes the driver name + as parameter.

+ +

The routine initializes the single global data structure and + returns a pointer to the driver entry. The routine will be + called when is called from Erlang.

+

The routine is called when a port is opened + from Erlang. In our case, we only allocate a structure and + initialize it. Creating the actual socket is left to the + routine.

+ fd = -1; +( 7) ud->lockfd = -1; +( 8) ud->creation = 0; +( 9) ud->port = port; +(10) ud->type = portTypeUnknown; +(11) ud->name = NULL; +(12) ud->buffer_size = 0; +(13) ud->buffer_pos = 0; +(14) ud->header_pos = 0; +(15) ud->buffer = NULL; +(16) ud->sent = 0; +(17) ud->received = 0; +(18) ud->partner = NULL; +(19) ud->next = first_data; +(20) first_data = ud; +(21) +(22) return((ErlDrvData) ud); +(23) } ]]> +

Every data item is initialized, so that no problems will arise + when a newly created port is closed (without there being any + corresponding socket). This routine is called when + is called from Erlang.

+

The routine is the routine called when an + Erlang process sends data to the port. All asynchronous + commands when the port is in command mode as well as + the sending of all data when the port is in data mode + is handled in this9s routine. Let's have a look at it:

+ type == portTypeData || ud->type == portTypeIntermediate) { +( 5) DEBUGF(("Passive do_send %d",bufflen)); +( 6) do_send(ud, buff + 1, bufflen - 1); /* XXX */ +( 7) return; +( 8) } +( 9) if (bufflen == 0) { +(10) return; +(11) } +(12) switch (*buff) { +(13) case 'L': +(14) if (ud->type != portTypeUnknown) { +(15) driver_failure_posix(ud->port, ENOTSUP); +(16) return; +(17) } +(18) uds_command_listen(ud,buff,bufflen); +(19) return; +(20) case 'A': +(21) if (ud->type != portTypeUnknown) { +(22) driver_failure_posix(ud->port, ENOTSUP); +(23) return; +(24) } +(25) uds_command_accept(ud,buff,bufflen); +(26) return; +(27) case 'C': +(28) if (ud->type != portTypeUnknown) { +(29) driver_failure_posix(ud->port, ENOTSUP); +(30) return; +(31) } +(32) uds_command_connect(ud,buff,bufflen); +(33) return; +(34) case 'S': +(35) if (ud->type != portTypeCommand) { +(36) driver_failure_posix(ud->port, ENOTSUP); +(37) return; +(38) } +(39) do_send(ud, buff + 1, bufflen - 1); +(40) return; +(41) case 'R': +(42) if (ud->type != portTypeCommand) { +(43) driver_failure_posix(ud->port, ENOTSUP); +(44) return; +(45) } +(46) do_recv(ud); +(47) return; +(48) default: +(49) return; +(50) } +(51) } ]]> +

The command routine takes three parameters; the handle + returned for the port by , which is a pointer + to the internal port structure, the data buffer and the length + of the data buffer. The buffer is the data sent from Erlang + (a list of bytes) converted to an C array (of bytes).

+

If Erlang sends i.e. the list to the port, + the variable will be ant the + variable will contain (no + null termination). Usually the first byte is used as an + opcode, which is the case in our driver to (at least when the + port is in command mode). The opcodes are defined as:

+ + 'L'<socketname>: Create and listen on socket with the + given name. + 'A'<listennumber as 32 bit bigendian>: Accept from the + listen socket identified by the given identification + number. The identification number is retrieved with the + uds_control routine. + 'C'<socketname>: Connect to the socket named + <socketname>. + 'S'<data>: Send the data <data> on the + connected/accepted socket (in command mode). The sending is + acked when the data has left this process. + 'R': Receive one packet of data. + +

One may wonder what is meant by "one packet of data" in the + 'R' command. This driver always sends data packeted with a 4 + byte header containing a big endian 32 bit integer that + represents the length of the data in the packet. There is no + need for different packet sizes or some kind of streamed + mode, as this driver is for the distribution only. One may + wonder why the header word is coded explicitly in big endian + when an UDS socket is local to the host. The answer simply is + that I see it as a good practice when writing a distribution + driver, as distribution in practice usually cross the host + boundaries.

+

On line 4-8 we handle the case where the port is in data or + intermediate mode, the rest of the routine handles the + different commands. We see (first on line 15) that the routine + uses the routine to report + errors. One important thing to remember is that the failure + routines make a call to our routine, which + will remove the internal port data. The handle (and the casted + handle ) is therefore invalid pointers after a + call and we should immediately return. The runtime system will send exit signals to all + linked processes.

+

The uds_input routine gets called when data is available on a + file descriptor previously passed to the + routine. Typically this happens when a read command is issued + and no data is available. Lets look at the + routine:

+ port, (ErlDrvEvent) ud->fd, DO_READ, 1); +( 9) } else { +(10) driver_failure_eof(ud->port); +(11) } +(12) return; +(13) } +(14) /* Got a package */ +(15) if (ud->type == portTypeCommand) { +(16) ibuf[-1] = 'R'; /* There is always room for a single byte +(17) opcode before the actual buffer +(18) (where the packet header was) */ +(19) driver_output(ud->port,ibuf - 1, res + 1); +(20) driver_select(ud->port, (ErlDrvEvent) ud->fd, DO_READ,0); +(21) return; +(22) } else { +(23) ibuf[-1] = DIST_MAGIC_RECV_TAG; /* XXX */ +(24) driver_output(ud->port,ibuf - 1, res + 1); +(25) driver_select(ud->port, (ErlDrvEvent) ud->fd, DO_READ,1); +(26) } +(27) } +(28) } ]]> +

The routine tries to read data until a packet is read or the + routine returns a + (an internally defined constant for + the module that means that the read operation resulted in an + ). If the port is in command mode, the + reading stops when one package is read, but if it is in data + mode, the reading continues until the socket buffer is empty + (read failure). If no more data can be read and more is wanted + (always the case when socket is in data mode) driver_select is + called to make the call-back be called when + more data is available for reading.

+

When the port is in data mode, all data is sent to Erlang in a + format that suits the distribution, in fact the raw data will + never reach any Erlang process, but will be + translated/interpreted by the emulator itself and then + delivered in the correct format to the correct processes. In + the current emulator version, received data should be tagged + with a single byte of 100. Thats what the macro + is defined to. The tagging of data + in the distribution will possibly change in the future.

+

The routine will handle other input events + (like nonblocking ), but most importantly handle + data arriving at the socket by calling :

+ type == portTypeListener) { +( 5) UdsData *ad = ud->partner; +( 6) struct sockaddr_un peer; +( 7) int pl = sizeof(struct sockaddr_un); +( 8) int fd; + +( 9) if ((fd = accept(ud->fd, (struct sockaddr *) &peer, &pl)) < 0) { +(10) if (errno != EWOULDBLOCK) { +(11) driver_failure_posix(ud->port, errno); +(12) return; +(13) } +(14) return; +(15) } +(16) SET_NONBLOCKING(fd); +(17) ad->fd = fd; +(18) ad->partner = NULL; +(19) ad->type = portTypeCommand; +(20) ud->partner = NULL; +(21) driver_select(ud->port, (ErlDrvEvent) ud->fd, DO_READ, 0); +(22) driver_output(ad->port, "Aok",3); +(23) return; +(24) } +(25) do_recv(ud); +(26) } ]]> +

The important line here is the last line in the function, the + routine is called to handle new input. The rest + of the function handles input on a listen socket, which means + that there should be possible to do an accept on the + socket, which is also recognized as a read event.

+

The output mechanisms are similar to the input. Lets first + look at the routine:

+ port) == 0) { +(19) if ((written = writev(ud->fd, iov, 2)) == eio.size) { +(20) ud->sent += written; +(21) if (ud->type == portTypeCommand) { +(22) driver_output(ud->port, "Sok", 3); +(23) } +(24) return; +(25) } else if (written < 0) { +(26) if (errno != EWOULDBLOCK) { +(27) driver_failure_eof(ud->port); +(28) return; +(29) } else { +(30) written = 0; +(31) } +(32) } else { +(33) ud->sent += written; +(34) } +(35) /* Enqueue remaining */ +(36) } +(37) driver_enqv(ud->port, &eio, written); +(38) send_out_queue(ud); +(39) } ]]> +

This driver uses the system call to send data + onto the socket. A combination of writev and the driver output + queues is very convenient. An ErlIOVec structure + contains a SysIOVec (which is equivalent to the + structure defined in . The + ErlIOVec also contains an array of ErlDrvBinary + pointers, of the same length as the number of buffers in the + 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 + (line 37).

+

+

The routine builds an I/O vector containing the header bytes + and the buffer (the opcode has been removed and the buffer + length decreased by the output routine). If the queue is + empty, we'll write the data directly to the socket (or at + least try to). If any data is left, it is stored in the queue + and then we try to send the queue (line 38). An ack is sent + when the message is delivered completely (line 22). The + will send acks if the sending is + completed there. If the port is in command mode, the Erlang + code serializes the send operations so that only one packet + can be waiting for delivery at a time. Therefore the ack can + be sent simply whenever the queue is empty.

+

+

A short look at the routine:

+ port, &vlen); +( 6) int wrote; +( 7) if (tmp == NULL) { +( 8) driver_select(ud->port, (ErlDrvEvent) ud->fd, DO_WRITE, 0); +( 9) if (ud->type == portTypeCommand) { +(10) driver_output(ud->port, "Sok", 3); +(11) } +(12) return 0; +(13) } +(14) if (vlen > IO_VECTOR_MAX) { +(15) vlen = IO_VECTOR_MAX; +(16) } +(17) if ((wrote = writev(ud->fd, tmp, vlen)) < 0) { +(18) if (errno == EWOULDBLOCK) { +(19) driver_select(ud->port, (ErlDrvEvent) ud->fd, +(20) DO_WRITE, 1); +(21) return 0; +(22) } else { +(23) driver_failure_eof(ud->port); +(24) return -1; +(25) } +(26) } +(27) driver_deq(ud->port, wrote); +(28) ud->sent += wrote; +(29) } +(30) } ]]> +

What we do is simply to pick out an I/O vector from the queue + (which is the whole queue as an SysIOVec). If the I/O + vector is to long (IO_VECTOR_MAX is defined to 16), the vector + length is decreased (line 15), otherwise the + (line 17) call will + fail. Writing is tried and anything written is dequeued (line + 27). If the write fails with (note that all + sockets are in nonblocking mode), is + called to make the routine be called when + there is space to write again.

+

We will continue trying to write until the queue is empty or + the writing would block.

+

The routine above are called from the + routine, which looks like this:

+ type == portTypeConnector) { +( 5) ud->type = portTypeCommand; +( 6) driver_select(ud->port, (ErlDrvEvent) ud->fd, DO_WRITE, 0); +( 7) driver_output(ud->port, "Cok",3); +( 8) return; +( 9) } +(10) send_out_queue(ud); +(11) } ]]> +

The routine is simple, it first handles the fact that the + output select will concern a socket in the business of + connecting (and the connecting blocked). If the socket is in + a connected state it simply sends the output queue, this + routine is called when there is possible to write to a socket + where we have an output queue, so there is no question what to + do.

+

The driver implements a control interface, which is a + synchronous interface called when Erlang calls + . This is the only interface + that can control the driver when it is in data mode and it may + be called with the following opcodes:

+ + 'C': Set port in command mode. + 'I': Set port in intermediate mode. + 'D': Set port in data mode. + 'N': Get identification number for listen port, this + identification number is used in an accept command to the + driver, it is returned as a big endian 32 bit integer, which + happens to be the file identifier for the listen socket. + 'S': Get statistics, which is the number of bytes received, + the number of bytes sent and the number of bytes pending in + the output queue. This data is used when the distribution + checks that a connection is alive (ticking). The statistics + is returned as 3 32 bit big endian integers. + 'T': Send a tick message, which is a packet of length + 0. Ticking is done when the port is in data mode, so the + command for sending data cannot be used (besides it ignores + zero length packages in command mode). This is used by the + ticker to send dummy data when no other traffic is present. + Note that it is important that the interface for + sending ticks is not blocking. This implementation uses + erlang:port_control/3 which does not block the caller. + If erlang:port_command is used, use + erlang:port_command/3 and pass [force] as + option list; otherwise, the caller can be blocked indefinitely + on a busy port and prevent the system from taking down a + connection that is not functioning. + 'R': Get creation number of listen socket, which is used to + dig out the number stored in the lock file to differentiate + between invocations of Erlang nodes with the same name.\011 + +

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 + to small. Here is the code for :

+ received); +(18) put_packet_length((*res) + 5, ud->sent); +(19) put_packet_length((*res) + 9, driver_sizeq(ud->port)); +(20) return 13; +(21) } +(22) case 'C': +(23) if (ud->type < portTypeCommand) { +(24) return report_control_error(res, res_size, "einval"); +(25) } +(26) ud->type = portTypeCommand; +(27) driver_select(ud->port, (ErlDrvEvent) ud->fd, DO_READ, 0); +(28) ENSURE(1); +(29) **res = 0; +(30) return 1; +(31) case 'I': +(32) if (ud->type < portTypeCommand) { +(33) return report_control_error(res, res_size, "einval"); +(34) } +(35) ud->type = portTypeIntermediate; +(36) driver_select(ud->port, (ErlDrvEvent) ud->fd, DO_READ, 0); +(37) ENSURE(1); +(38) **res = 0; +(39) return 1; +(40) case 'D': +(41) if (ud->type < portTypeCommand) { +(42) return report_control_error(res, res_size, "einval"); +(43) } +(44) ud->type = portTypeData; +(45) do_recv(ud); +(46) ENSURE(1); +(47) **res = 0; +(48) return 1; +(49) case 'N': +(50) if (ud->type != portTypeListener) { +(51) return report_control_error(res, res_size, "einval"); +(52) } +(53) ENSURE(5); +(54) (*res)[0] = 0; +(55) put_packet_length((*res) + 1, ud->fd); +(56) return 5; +(57) case 'T': /* tick */ +(58) if (ud->type != portTypeData) { +(59) return report_control_error(res, res_size, "einval"); +(60) } +(61) do_send(ud,"",0); +(62) ENSURE(1); +(63) **res = 0; +(64) return 1; +(65) case 'R': +(66) if (ud->type != portTypeListener) { +(67) return report_control_error(res, res_size, "einval"); +(68) } +(69) ENSURE(2); +(70) (*res)[0] = 0; +(71) (*res)[1] = ud->creation; +(72) return 2; +(73) default: +(74) return report_control_error(res, res_size, "einval"); +(75) } +(76) #undef ENSURE +(77) } ]]> +

The macro (line 5 to 10) is used to ensure that + the buffer is large enough for our answer. We switch on the + command and take actions, there is not much to say about this + routine. Worth noting is that we always has read select active + on a port in data mode (achieved by calling on + line 45), but turn off read selection in intermediate and + command modes (line 27 and 36).

+

The rest of the driver is more or less UDS specific and not of + general interest.

+
+
+ +
+ Putting it all together +

To test the distribution, one can use the + function, which is useful as it starts + the distribution on a running system, where tracing/debugging + can be performed. The routine takes a + list as it's 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 or + . In the example case is + preferred.

+

For net kernel to find out which distribution module to use, the + command line argument is used. The argument + is followed by one or more distribution module names, with the + "_dist" suffix removed, i.e. uds_dist as a distribution module + is specified as .

+

If no epmd (TCP port mapper daemon) is used, one should also + specify the command line option , which will make + Erlang skip the epmd startup, both as a OS process and as an + Erlang ditto.

+

The path to the directory where the distribution modules reside + must be known at boot, which can either be achieved by + specifying ]]> on the command line or by building + a boot script containing the applications used for your + distribution protocol (in the uds_dist protocol, it's only the + uds_dist application that needs to be added to the script).

+

The distribution will be started at boot if all the above is + specified and an ]]> flag is present at the + command line, here follows two examples:

+ 
+$ erl -pa $ERL_TOP/lib/kernel/examples/uds_dist/ebin -proto_dist uds -no_epmd
+Erlang (BEAM) emulator version 5.0 
+ 
+Eshell V5.0  (abort with ^G)
+1> net_kernel:start([bing,shortnames]).
+{ok,<0.30.0>}
+(bing@hador)2>
+

...

+ 
+$ erl -pa $ERL_TOP/lib/kernel/examples/uds_dist/ebin -proto_dist uds \\ 
+      -no_epmd -sname bong
+Erlang (BEAM) emulator version 5.0 
+ 
+Eshell V5.0  (abort with ^G)
+(bong@hador)1>
+

One can utilize the ERL_FLAGS environment variable to store the + complicated parameters in:

+ 
+$ ERL_FLAGS=-pa $ERL_TOP/lib/kernel/examples/uds_dist/ebin \\ 
+      -proto_dist uds -no_epmd
+$ export ERL_FLAGS
+$ erl -sname bang
+Erlang (BEAM) emulator version 5.0 
+ 
+Eshell V5.0  (abort with ^G)
+(bang@hador)1>
+

The should preferably not include the name of + the node.

+
+ + diff --git a/erts/doc/src/book.xml b/erts/doc/src/book.xml new file mode 100644 index 0000000000..00a2888685 --- /dev/null +++ b/erts/doc/src/book.xml @@ -0,0 +1,49 @@ + + + + +
+ + 19972009 + Ericsson AB. 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. + + + + Erlang Run-Time System Application (ERTS) + Magnus Fröberg + + 1997-05-02 + 4.5.2 + book.xml +
+ + + Erlang Run-Time System Application (ERTS) + + + + + + + + + + + + + + + + diff --git a/erts/doc/src/crash_dump.xml b/erts/doc/src/crash_dump.xml new file mode 100644 index 0000000000..5182929358 --- /dev/null +++ b/erts/doc/src/crash_dump.xml @@ -0,0 +1,518 @@ + + + + +
+ + 19992009 + Ericsson AB. 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. + + + + How to interpret the Erlang crash dumps + Patrik Nyblom + + + + + 1999-11-11 + PA1 + crash_dump.xml +
+

This document describes the file generated + upon abnormal exit of the Erlang runtime system.

+

Important: For OTP release R9C the Erlang crash dump has + had a major facelift. This means that the information in this + document will not be directly applicable for older dumps. However, + if you use the Crashdump Viewer tool on older dumps, the crash + dumps are translated into a format similar to this.

+

The system will write the crash dump in the current directory of + the emulator or in the file pointed out by the environment variable + (whatever that means on the current operating system) + ERL_CRASH_DUMP. For a crash dump to be written, there has to be a + writable file system mounted.

+

Crash dumps are written mainly for one of two reasons: either the + builtin function is called explicitly with a + string argument from running Erlang code, or else the runtime + system has detected an error that cannot be handled. The most + usual reason that the system can't handle the error is that the + cause is external limitations, such as running out of memory. A + crash dump due to an internal error may be caused by the system + reaching limits in the emulator itself (like the number of atoms + in the system, or too many simultaneous ets tables). Usually the + emulator or the operating system can be reconfigured to avoid the + crash, which is why interpreting the crash dump correctly is + important.

+

The erlang crash dump is a readable text file, but it might not be + very easy to read. Using the Crashdump Viewer tool in the + application will simplify the task. This is an + HTML based tool for browsing Erlang crash dumps.

+ +
+ + General information +

The first part of the dump shows the creation time for the dump, + a slogan indicating the reason for the dump, the system version, + of the node from which the dump originates, the compile time of + the emulator running the originating node and the number of + atoms in the atom table. +

+ +
+ Reasons for crash dumps (slogan) +

The reason for the dump is noted in the beginning of the file + as Slogan: <reason> (the word "slogan" has historical + roots). If the system is halted by the BIF + , the slogan is the string parameter + passed to the BIF, otherwise it is a description generated by + the emulator or the (Erlang) kernel. Normally the message + should be enough to understand the problem, but nevertheless + some messages are described here. Note however that the + suggested reasons for the crash are only suggestions. The exact reasons for the errors may vary + depending on the local applications and the underlying + operating system.

+ + "<A>: Cannot allocate <N> + bytes of memory (of type "<T>")." - The system + has run out of memory. <A> is the allocator that failed + to allocate memory, <N> is the number of bytes that + <A> tried to allocate, and <T> is the memory block + type that the memory was needed for. The most common case is + that a process stores huge amounts of data. In this case + <T> is most often , , + , or . For more information on + allocators see + erts_alloc(3). + "<A>: Cannot reallocate <N> + bytes of memory\011(of type "<T>")." - Same as + above with the exception that memory was being reallocated + instead of being allocated when the system ran out of memory. + "Unexpected op code N" - Error in compiled + code, file damaged or error in the compiler. + "Module Name undefined" "Function + Name undefined" "No function + Name:Name/1" "No function + Name:start/2" - The kernel/stdlib applications are + damaged or the start script is damaged. + "Driver_select called with too large file descriptor + " - The number of file descriptors for sockets + exceed 1024 (Unix only). The limit on file-descriptors in + some Unix flavors can be set to over 1024, but only 1024 + sockets/pipes can be used simultaneously by Erlang (due to + limitations in the Unix call). The number of + open regular files is not affected by this. + "Received SIGUSR1" - The SIGUSR1 signal was sent to the + Erlang machine (Unix only). + "Kernel pid terminated (Who) + (Exit-reason)" - The kernel supervisor has detected + a failure, usually that the + has shut down ( = , + = ). The application controller + may have shut down for a number of reasons, the most usual + being that the node name of the distributed Erlang node is + already in use. A complete supervisor tree "crash" (i.e., + the top supervisors have exited) will give about the same + result. This message comes from the Erlang code and not from + the virtual machine itself. It is always due to some kind of + failure in an application, either within OTP or a + "user-written" one. Looking at the error log for your + application is probably the first step to take. + "Init terminating in do_boot ()" - The primitive Erlang boot + sequence was terminated, most probably because the boot + script has errors or cannot be read. This is usually a + configuration error - the system may have been started with + a faulty parameter or with a boot script from + the wrong version of OTP. + "Could not start kernel pid (Who) ()" - One of the + kernel processes could not start. This is probably due to + faulty arguments (like errors in a argument) + or faulty configuration files. Check that all files are in + their correct location and that the configuration files (if + any) are not damaged. Usually there are also messages + written to the controlling terminal and/or the error log + explaining what's wrong. + +

Other errors than the ones mentioned above may occur, as the + BIF may generate any message. If the + message is not generated by the BIF and does not occur in the + list above, it may be due to an error in the emulator. There + may however be unusual messages that I haven't mentioned, that + still are connected to an application failure. There is a lot + more information available, so more thorough reading of the + crash dump may reveal the crash reason. The size of processes, + the number of ets tables and the Erlang data on each process + stack can be useful for tracking down the problem.

+
+ +
+ Number of atoms +

The number of atoms in the system at the time of the crash is + shown as Atoms: <number>. Some ten thousands atoms is + perfectly normal, but more could indicate that the BIF + is used to dynamically generate a + lot of different atoms, which is never a good idea.

+
+
+ +
+ + Memory information +

Under the tag =memory you will find information similar + to what you can obtain on a living node with + erlang:memory().

+
+ +
+ + Internal table information +

The tags =hash_table:<table_name> and + =index_table:<table_name> presents internal + tables. These are mostly of interest for runtime system + developers.

+
+ +
+ + Allocated areas +

Under the tag =allocated_areas you will find information + similar to what you can obtain on a living node with + erlang:system_info(allocated_areas).

+
+ +
+ + Allocator +

Under the tag =allocator:<A> you will find + various information about allocator <A>. The information + is similar to what you can obtain on a living node with + erlang:system_info({allocator, <A>}). + For more information see the documentation of + erlang:system_info({allocator, <A>}), + and the + erts_alloc(3) + documentation.

+
+ +
+ + Process information +

The Erlang crashdump contains a listing of each living Erlang + process in the system. The process information for one process + may look like this (line numbers have been added): +

+

The following fields can exist for a process:

+ + =proc:<pid> + Heading, states the process identifier + State + +

The state of the process. This can be one of the following:

+ + Scheduled - The process was scheduled to run + but not currently running ("in the run queue"). + Waiting - The process was waiting for + something (in ). + Running - The process was currently + running. If the BIF was called, this was + the process calling it. + Exiting - The process was on its way to + exit. + Garbing - This is bad luck, the process was + garbage collecting when the crash dump was written, the rest + of the information for this process is limited. + Suspended - The process is suspended, either + by the BIF or because it is + trying to write to a busy port. + + + Registered name + The registered name of the process, if any. + Spawned as + The entry point of the process, i.e., what function was + referenced in the or call that + started the process. + Last scheduled in for | Current call + The current function of the process. These fields will not + always exist. + Spawned by + The parent of the process, i.e. the process which executed + or . + Started + The date and time when the process was started. + Message queue length + The number of messages in the process' message queue. + Number of heap fragments + The number of allocated heap fragments. + Heap fragment data + Size of fragmented heap data. This is data either created by + messages being sent to the process or by the Erlang BIFs. This + amount depends on so many things that this field is utterly + uninteresting. + Link list + Process id's of processes linked to this one. May also contain + ports. If process monitoring is used, this field also tells in + which direction the monitoring is in effect, i.e., a link + being "to" a process tells you that the "current" process was + monitoring the other and a link "from" a process tells you + that the other process was monitoring the current one. + Reductions + The number of reductions consumed by the process. + Stack+heap + The size of the stack and heap (they share memory segment) + OldHeap + The size of the "old heap". The Erlang virtual machine uses + generational garbage collection with two generations. There is + one heap for new data items and one for the data that have + survived two garbage collections. The assumption (which is + almost always correct) is that data that survive two garbage + collections can be "tenured" to a heap more seldom garbage + collected, as they will live for a long period. This is a + quite usual technique in virtual machines. The sum of the + heaps and stack together constitute most of the process's + allocated memory. + Heap unused, OldHeap unused + The amount of unused memory on each heap. This information is + usually useless. + Stack + If the system uses shared heap, the fields + Stack+heap, OldHeap, Heap unused + and OldHeap unused do not exist. Instead this field + presents the size of the process' stack. + Program counter + The current instruction pointer. This is only interesting for + runtime system developers. The function into which the program + counter points is the current function of the process. + CP + The continuation pointer, i.e. the return address for the + current call. Usually useless for other than runtime system + developers. This may be followed by the function into which + the CP points, which is the function calling the current + function. + Arity + The number of live argument registers. The argument registers, + if any are live, will follow. These may contain the arguments + of the function if they are not yet moved to the stack. + +

See also the section about process data.

+
+ +
+ + Port information +

This section lists the open ports, their owners, any linked + processed, and the name of their driver or external process.

+
+ +
+ + ETS tables +

This section contains information about all the ETS tables in + the system. The following fields are interesting for each table:

+ + =ets:<owner> + Heading, states the owner of the table (a process identifier) + Table + The identifier for the table. If the table is a + , this is the name. + Name + The name of the table, regardless of whether it is a + or not. + Buckets + This occurs if the table is a hash table, i.e. if it is not an + . + Ordered set (AVL tree), Elements + This occurs only if the table is an . (The + number of elements is the same as the number of objects in the + table.) + Objects + The number of objects in the table + Words + The number of words (usually 4 bytes/word) allocated to data + in the table. + +
+ +
+ + Timers +

This section contains information about all the timers started + with the BIFs and + . The following fields exists for each + timer:

+ + =timer:<owner> + Heading, states the owner of the timer (a process identifier) + i.e. the process to receive the message when the timer + expires. + Message + The message to be sent. + Time left + Number of milliseconds left until the message would have been + sent. + +
+ +
+ + Distribution information +

If the Erlang node was alive, i.e., set up for communicating + with other nodes, this section lists the connections that were + active. The following fields can exist:

+ + =node:<node_name> + The name of the node + no_distribution + This will only occur if the node was not distributed. + =visible_node:<channel> + Heading for a visible nodes, i.e. an alive node with a + connection to the node that crashed. States the channel number + for the node. + =hidden_node:<channel> + Heading for a hidden node. A hidden node is the same as a + visible node, except that it is started with the "-hidden" + flag. States the channel number for the node. + =not_connected:<channel> + Heading for a node which is has been connected to the crashed + node earlier. References (i.e. process or port identifiers) + to the not connected node existed at the time of the crash. + exist. States the channel number for the node. + Name + The name of the remote node. + Controller + The port which controls the communication with the remote node. + Creation + An integer (1-3) which together with the node name identifies + a specific instance of the node. + Remote monitoring: <local_proc> <remote_proc> + The local process was monitoring the remote process at the + time of the crash. + Remotely monitored by: <local_proc> <remote_proc> + The remote process was monitoring the local process at the + time of the crash. + Remote link: <local_proc> <remote_proc> + A link existed between the local process and the remote + process at the time of the crash. + +
+ +
+ + Loaded module information +

This section contains information about all loaded modules. + First, the memory usage by loaded code is summarized. There is + one field for "Current code" which is code that is the current + latest version of the modules. There is also a field for "Old + code" which is code where there exists a newer version in the + system, but the old version is not yet purged. The memory usage + is in bytes.

+

All loaded modules are then listed. The following fields exist:

+ + =mod:<module_name> + Heading, and the name of the module. + Current size + Memory usage for the loaded code in bytes + Old size + Memory usage for the old code, if any. + Current attributes + Module attributes for the current code. This field is decoded + when looked at by the Crashdump Viewer tool. + Old attributes + Module attributes for the old code, if any. This field is + decoded when looked at by the Crashdump Viewer tool. + Current compilation info + Compilation information (options) for the current code. This + field is decoded when looked at by the Crashdump Viewer tool. + Old compilation info + Compilation information (options) for the old code, if + any. This field is decoded when looked at by the Crashdump + Viewer tool. + +
+ +
+ + Fun information +

In this section, all funs are listed. The following fields exist + for each fun:

+ + =fun + Heading + Module + The name of the module where the fun was defined. + Uniq, Index + Identifiers + Address + The address of the fun's code. + Native_address + The address of the fun's code when HiPE is enabled. + Refc + The number of references to the fun. + +
+ +
+ + Process Data +

For each process there will be at least one =proc_stack + and one =proc_heap tag followed by the raw memory + information for the stack and heap of the process.

+

For each process there will also be a =proc_messages + tag if the process' message queue is non-empty and a + =proc_dictionary tag if the process' dictionary (the + and thing) is non-empty.

+

The raw memory information can be decoded by the Crashdump + Viewer tool. You will then be able to see the stack dump, the + message queue (if any) and the dictionary (if any).

+

The stack dump is a dump of the Erlang process stack. Most of + the live data (i.e., variables currently in use) are placed on + the stack; thus this can be quite interesting. One has to + "guess" what's what, but as the information is symbolic, + thorough reading of this information can be very useful. As an + example we can find the state variable of the Erlang primitive + loader on line in the example below:

+ ) +(2) y(0) ["/view/siri_r10_dev/clearcase/otp/erts/lib/kernel/ebin","/view/siri_r10_dev/ +(3) clearcase/otp/erts/lib/stdlib/ebin"] +(4) y(1) <0.1.0> +(5) y(2) {state,[],none,#Fun,undefined,#Fun,#Fun,#Port<0.2>,infinity,#Fun} +(6) y(3) infinity ]]> +

When interpreting the data for a process, it is helpful to know + that anonymous function objects (funs) are given a name + constructed from the name of the function in which they are + created, and a number (starting with 0) indicating the number of + that fun within that function.

+
+ +
+ + Atoms +

Now all the atoms in the system are written. This is only + interesting if one suspects that dynamic generation of atoms could + be a problem, otherwise this section can be ignored.

+

Note that the last created atom is printed first.

+
+ +
+ Disclaimer +

The format of the crash dump evolves between releases of + OTP. Some information here may not apply to your + version. A description as this will never be complete; it is meant as + an explanation of the crash dump in general and as a help + when trying to find application errors, not as a complete + specification.

+
+ + diff --git a/erts/doc/src/driver.xml b/erts/doc/src/driver.xml new file mode 100644 index 0000000000..c396ee0b90 --- /dev/null +++ b/erts/doc/src/driver.xml @@ -0,0 +1,812 @@ + + + + +
+ + 20012009 + Ericsson AB. 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. + + + + How to implement a driver + Jakob C + + 2000-11-28 + PA1 + driver.xml +
+ +

This document was written a long time ago. A lot of it is still + valid, but some things have changed since it was first written. + Updates of this document are planned for the future. The reader + is encouraged to also read the + erl_driver, and the + driver_entry documentation. +

+ +
+ Introduction +

This chapter tells you how to build your own driver for erlang.

+

A driver in Erlang is a library written in C, that is linked to + the Erlang emulator and called from erlang. Drivers can be used + when C is more suitable than Erlang, to speed things up, or to + provide access to OS resources not directly accessible from + Erlang.

+

A driver can be dynamically loaded, as a shared library (known as + a DLL on windows), or statically loaded, linked with the emulator + when it is compiled and linked. Only dynamically loaded drivers + are described here, statically linked drivers are beyond the scope + of this chapter.

+

When a driver is loaded it is executed in the context of the + emulator, shares the same memory and the same thread. This means + that all operations in the driver must be non-blocking, and that + any crash in the driver will bring the whole emulator down. In + short: you have to be extremely careful!

+

+
+ +
+ Sample driver +

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.

+

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 + halt the emulator while waiting for the database. + This will be improved on below with an asynchronous + sample driver.

+

The code is quite straight-forward: all + communication between Erlang and the driver + is done with , and the + driver returns data back using the .

+

An Erlang driver only exports one function: the driver + entry function. This is defined with a macro, + , and returns a pointer to a + C containing the entry points that are + called from the emulator. The defines the + entries that the emulator calls to call the driver, with + a pointer for entries that are not defined + and used by the driver.

+

The entry is called when the driver + is opened as a port with . Here + we allocate memory for a user data structure. + This user data will be passed every time the emulator + calls us. First we store the driver handle, because it + is needed in subsequent calls. We allocate memory for + the connection handle that is used by LibPQ. We also + set the port to return allocated driver binaries, by + setting the flag , calling + . (This is because + we don't know whether our data will fit in the + result buffer of , which has a default size + set up by the emulator, currently 64 bytes.)

+

There is an entry which is called when + the driver is loaded, but we don't use this, since + it is executed only once, and we want to have the + possibility of several instances of the driver.

+

The entry is called when the port + is closed.

+

The entry is called from the emulator + when the Erlang code calls , + to do the actual work. We have defined a simple set of + commands: to login to the database, + to log out and to send a SQL-query and get the result. + All results are returned through . + The library in is used + to encode data in binary term format. The result is returned + to the emulator as binary terms, so + is called in Erlang to convert the result to term form.

+

The code is available in in the + directory of .

+

The driver entry contains the functions that + will be called by the emulator. In our simple + example, we only provide , + and .

+ +

We have a structure to store state needed by the driver, + in this case we only need to keep the database connection.

+ +

These are control codes we have defined.

+ +

This just returns the driver structure. The macro + defines the only exported function. + All the other functions are static, and will not be exported + from the library.

+ +

Here we do some initialization, is called from + . The data will be passed to + and .

+ conn = NULL; + set_port_control_flags(port, PORT_CONTROL_FLAG_BINARY); + return (ErlDrvData)data; +} + ]]> +

We call disconnect to log out from the database. + (This should have been done from Erlang, but just in case.)

+ +

We use the binary format only to return data to the emulator; + input data is a string paramater for and + . The returned data consists of Erlang terms.

+

The functions and are + utilities that is used to make the code shorter. + duplicates the string and zero-terminates it, since the + postgres client library wants that. + takes an buffer and allocates a binary and + copies the data there. This binary is returned in . + (Note that this binary is freed by the emulator, not by us.)

+ +

In 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 in the driver data.

+ conn = conn; + return 0; +} + ]]> +

If we are connected (if the connection handle is not ), + we log out from the database. We need to check if a we should + encode an ok, since we might get here from the + function, which doesn't return data to the emulator.

+ conn == NULL) + return 0; + PQfinish(data->conn); + data->conn = NULL; + if (x != NULL) + encode_ok(x); + return 0; +} + ]]> +

We execute a query and encodes the result. Encoding is done + in another C module, which is also provided + as sample code.

+ conn, s); + encode_result(x, res, data->conn); + PQclear(res); + return 0; +} + ]]> +

Here we simply checks 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 to send + the result as strings to Erlang. (The head of the list + contains the column names.)

+ +
+ +
+ Compiling and linking the sample driver +

The driver should be compiled and linked to a shared + library (DLL on windows). With gcc this is done + with the link flags and . + Since we use the library we should include + it too. There are several versions of , compiled + for debug or non-debug and multi-threaded or single-threaded. + In the makefile for the samples the directory + is used for the library, meaning that we use + the non-debug, single-threaded version.

+
+ +
+ Calling a driver as a port in Erlang +

Before a driver can be called from Erlang, it must be + loaded and opened. Loading is done using the + module (the driver that loads dynamic + driver, is actually a driver itself). If loading is ok + the port can be opened with . The port + name must match the name of the shared library and + the name in the driver entry structure.

+

When the port has been opened, the driver can be called. In + the example, we don't have any data from + the port, only the return value from the + .

+

The following code is the Erlang part of the synchronous + postgres driver, .

+ + case erl_ddll:load_driver(".", "pg_sync") of + ok -> ok; + {error, already_loaded} -> ok; + E -> exit({error, E}) + end, + Port = open_port({spawn, ?MODULE}, []), + case binary_to_term(port_control(Port, ?DRV_CONNECT, ConnectStr)) of + ok -> {ok, Port}; + Error -> Error + end. + +disconnect(Port) -> + R = binary_to_term(port_control(Port, ?DRV_DISCONNECT, "")), + port_close(Port), + R. + +select(Port, Query) -> + binary_to_term(port_control(Port, ?DRV_SELECT, Query)). + ]]> +

The api is simple: loads the driver, opens it + and logs on to the database, returning the Erlang port + if successful, sends a query to the driver, + and returns the result, closes the + database connection and the driver. (It does not unload it, + however.) The connection string should be a connection + string for postgres.

+

The driver is loaded with , + and if this is successful, or if it's already loaded, + it is opened. This will call the function + in the driver.

+

We use the function for all + calls into the driver, the result from the driver is + returned immediately, and converted to terms by calling + . (We trust that the terms returned + from the driver are well-formed, otherwise the + calls could be contained in a + .)

+
+ +
+ Sample asynchronous driver +

Sometimes database queries can take long time to + complete, in our driver, the emulator + halts while the driver is doing it's job. This is + often not acceptable, since no other Erlang processes + gets a chance to do anything. To improve on our + postgres driver, we reimplement it using the asynchronous + calls in LibPQ.

+

The asynchronous version of the driver is in the + sample files and .

+ +

Here some things have changed from : we use the + entry for and + which will be called from the emulator only + when there is input to be read from the socket. (Actually, the + socket is used in a function inside + the emulator, and when the socket is signalled, + indicating there is data to read, the entry + is called. More on this below.)

+

Our driver data is also extended, we keep track of the + socket used for communication with postgres, and also + the port, which is needed when we send data to the port with + . We have a flag to tell + whether the driver is waiting for a connection or waiting + for the result of a query. (This is needed since the entry + will be called both when connecting and + when there is query result.)

+ port, x.buff, x.index); + ei_x_free(&x); + } + PQconnectPoll(conn); + int socket = PQsocket(conn); + data->socket = socket; + driver_select(data->port, (ErlDrvEvent)socket, DO_READ, 1); + driver_select(data->port, (ErlDrvEvent)socket, DO_WRITE, 1); + data->conn = conn; + data->connecting = 1; + return 0; +} + ]]> +

The function looks a bit different too. We connect + using the asynchronous function. After the + connection is started, we retrieve the socket for the connection + with . This socket is used with the + function to wait for connection. When + the socket is ready for input or for output, the + function will be called.

+

Note that we only return data (with ) if there + is an error here, otherwise we wait for the connection to be completed, + in which case our function will be called.

+ connecting = 0; + PGconn* conn = data->conn; + /* if there's an error return it now */ + if (PQsendQuery(conn, s) == 0) { +\011ei_x_buff x; +\011ei_x_new_with_version(&x); +\011encode_error(&x, conn); +\011driver_output(data->port, x.buff, x.index); +\011ei_x_free(&x); + } + /* else wait for ready_output to get results */ + return 0; +} + ]]> +

The function initiates a select, and returns + if there is no immediate error. The actual result will be returned + when is called.

+ conn; + ei_x_buff x; + ei_x_new_with_version(&x); + if (data->connecting) { +\011ConnStatusType status; +\011PQconnectPoll(conn); +\011status = PQstatus(conn); +\011if (status == CONNECTION_OK) +\011 encode_ok(&x); +\011else if (status == CONNECTION_BAD) +\011 encode_error(&x, conn); + } else { +\011PQconsumeInput(conn); +\011if (PQisBusy(conn)) +\011 return; +\011res = PQgetResult(conn); +\011encode_result(&x, res, conn); +\011PQclear(res); +\011for (;;) { +\011 res = PQgetResult(conn); +\011 if (res == NULL) +\011\011break; +\011 PQclear(res); +\011} + } + if (x.index > 1) { +\011driver_output(data->port, x.buff, x.index); +\011if (data->connecting) +\011 driver_select(data->port, (ErlDrvEvent)data->socket, DO_WRITE, 0); + } + ei_x_free(&x); +} + ]]> +

The function will be called when the socket + we got from postgres is ready for input or output. Here + we first check if we are connecting to the database. In that + case we check connection status and return ok if the + connection is successful, or error if it's not. If the + connection is not yet established, we simply return; + will be called again.

+

If we have result from a connect, indicated that we have data in + the buffer, we no longer need to select on + output (), so we remove this by calling + .

+

If we're not connecting, we're waiting for results from a + , so we get the result and return it. The + encoding is done with the same functions as in the earlier + example.

+

We should add error handling here, for instance checking + that the socket is still open, but this is just a simple + example.

+

The Erlang part of the asynchronous driver consists of the + sample file .

+ + case erl_ddll:load_driver(".", "pg_async") of +\011ok -> ok; +\011{error, already_loaded} -> ok; +\011_ -> exit({error, could_not_load_driver}) + end, + Port = open_port({spawn, ?MODULE}, [binary]), + port_control(Port, ?DRV_CONNECT, ConnectStr), + case return_port_data(Port) of +\011ok -> +\011 {ok, Port}; +\011Error -> +\011 Error + end. + +disconnect(Port) -> + port_control(Port, ?DRV_DISCONNECT, ""), + R = return_port_data(Port), + port_close(Port), + R. + +select(Port, Query) -> + port_control(Port, ?DRV_SELECT, Query), + return_port_data(Port). + +return_port_data(Port) -> + receive +\011{Port, {data, Data}} -> +\011 binary_to_term(Data) + end. + ]]> +

The Erlang code is slightly different, this is because we + don't return the result synchronously from , + instead we get it from as data in the + message queue. The function above + receives data from the port. Since the data is in + binary format, we use to convert + it to Erlang term. Note that the driver is opened in + binary mode, is called with the option + . This means that data sent from the driver + to the emulator is sent as binaries. Without the + option, they would have been lists of integers.

+
+ +
+ An asynchronous driver using driver_async +

As a final example we demonstrate the use of . + We also use the driver term interface. The driver is written + in C++. This enables us to use an algorithm from STL. We will + use the algorithm to get the next permutation + 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.

+

The asynchronous api for drivers are quite complicated. First + of all, the work must be prepared. In our example we do this + in . We could have used 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 + 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. + Finally, after the function is completed, the driver callback + is called from the main emulator thread, + this is where we return the result to Erlang. (We can't + return the result from within the asynchronous function, since + we can't call the driver-functions.)

+

The code below is from the sample file .

+

The driver entry looks like before, but also contains the + call-back .

+ +

The function allocates the work-area of the + asynchronous function. Since we use C++, we use a struct, + and stuff the data in it. We have to copy the original data, + it is not valid after we have returned from the + function, and the function will be called later, + and from another thread. We return no data here, instead it will + be sent later from the call-back.

+

The will be passed to the function. + We do not use a function (the last argument to + , it's only used if the task is cancelled + programmatically.

+ data; + our_async_data(ErlDrvPort p, int command, const char* buf, int len); +}; + +our_async_data::our_async_data(ErlDrvPort p, int command, +\011\011\011 const char* buf, int len) + : prev(command == 2), + data((int*)buf, (int*)buf + len / sizeof(int)) +{ +} + +static void do_perm(void* async_data); + +static void output(ErlDrvData drv_data, char *buf, int len) +{ + if (*buf < 1 || *buf > 2) return; + ErlDrvPort port = reinterpret_cast(drv_data); + void* async_data = new our_async_data(port, *buf, buf+1, len); + driver_async(port, NULL, do_perm, async_data, do_free); +} + ]]> +

In the we simply do the work, operating + on the structure that was allocated in .

+ (async_data); + if (d->prev) +\011prev_permutation(d->data.begin(), d->data.end()); + else +\011next_permutation(d->data.begin(), d->data.end()); +} + ]]> +

In the function, the output is sent back to the + emulator. We use the driver term format instead of . + This is the only way to send Erlang terms directly to a driver, + without having the Erlang code to call . In + our simple example this works well, and we don't need to use + to handle the binary term format.

+

When the data is returned we deallocate our data.

+ (drv_data); + our_async_data* d = reinterpret_cast(async_data); + int n = d->data.size(), result_n = n*2 + 3; + ErlDrvTermData* result = new ErlDrvTermData[result_n], * rp = result; + for (vector::iterator i = d->data.begin(); +\011 i != d->data.end(); ++i) { +\011*rp++ = ERL_DRV_INT; +\011*rp++ = *i; + } + *rp++ = ERL_DRV_NIL; + *rp++ = ERL_DRV_LIST; + *rp++ = n+1; + driver_output_term(port, result, result_n); + delete[] result; + delete d; +} + ]]> +

This driver is called like the others from Erlang, however, since + we use , there is no need to call + binary_to_term. The Erlang code is in the sample file + .

+

The input is changed into a list of integers and sent to + the driver.

+ + case whereis(next_perm) of +\011undefined -> +\011 case erl_ddll:load_driver(".", "next_perm") of +\011\011ok -> ok; +\011\011{error, already_loaded} -> ok; +\011\011E -> exit(E) +\011 end, +\011 Port = open_port({spawn, "next_perm"}, []), +\011 register(next_perm, Port); +\011_ -> +\011 ok + end. + +list_to_integer_binaries(L) -> + [<> || I <- L]. + +next_perm(L) -> + next_perm(L, 1). + +prev_perm(L) -> + next_perm(L, 2). + +next_perm(L, Nxt) -> + load(), + B = list_to_integer_binaries(L), + port_control(next_perm, Nxt, B), + receive +\011Result -> +\011 Result + end. + +all_perm(L) -> + New = prev_perm(L), + all_perm(New, L, [New]). + +all_perm(L, L, Acc) -> + Acc; +all_perm(L, Orig, Acc) -> + New = prev_perm(L), + all_perm(New, Orig, [New | Acc]). + ]]> +
+ + diff --git a/erts/doc/src/driver_entry.xml b/erts/doc/src/driver_entry.xml new file mode 100644 index 0000000000..6b7d2acf24 --- /dev/null +++ b/erts/doc/src/driver_entry.xml @@ -0,0 +1,453 @@ + + + + +
+ + 20012009 + Ericsson AB. 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. + + + + driver_entry + Jakob Cederlund + Jakob Cederlund + 1 + + + 2001-10-01 + PA1 + driver_entry.xml +
+ driver_entry + The driver-entry structure used by erlang drivers. + +

As of erts version 5.5.3 the driver interface has been extended + (see extended marker). + The extended interface introduce + version management, + the possibility to pass capability flags + (see driver flags) + to the runtime system at driver initialization, and some new + driver API functions.

+ +

Old drivers (compiled with an erl_driver.h from an + earlier erts version than 5.5.3) have to be recompiled + (but does not have to use the extended interface).

+ +

The driver_entry structure is a C struct that all erlang + drivers defines. It contains entry points for the erlang driver + that are called by the erlang emulator when erlang code accesses + the driver.

+

+ + The erl_driver driver + API functions needs a port handle + that identifies the driver instance (and the port in the + emulator). This is only passed to the start function, but + not to the other functions. The start function returns a + driver-defined handle that is passed to the other functions. A + common practice is to have the start function allocating + some application-defined structure and stash the port + handle in it, to use it later with the driver API functions.

+

The driver call-back functions are called synchronously from the + erlang emulator. If they take too long before completing, they + can cause timeouts in the emulator. Use the queue or + asynchronous calls if necessary, since the emulator must be + responsive.

+

The driver structure contains the name of the driver and some + 15 function pointers. These pointers are called at different + times by the emulator.

+

The only exported function from the driver is + driver_init. This function returns the driver_entry + structure that points to the other functions in the driver. The + driver_init function is declared with a macro + DRIVER_INIT(drivername). (This is because different OS's + have different names for it.)

+

When writing a driver in C++, the driver entry should be of + "C" linkage. One way to do this is to put this line + somewhere before the driver entry: + extern "C" DRIVER_INIT(drivername);.

+

When the driver has passed the driver_entry over to + the emulator, the driver is not allowed to modify the + driver_entry.

+ +

Do not declare the driver_entryconst. This since the emulator needs to + modify the handle, and the handle2 + fields. A statically allocated, and const + declared driver_entry may be located in + read only memory which will cause the emulator + to crash.

+ + + +
+ DATA TYPES + + ErlDrvEntry + +

+ +typedef struct erl_drv_entry { + int (*init)(void); /* called at system start up for statically + linked drivers, and after loading for + dynamically loaded drivers */ + +#ifndef ERL_SYS_DRV + ErlDrvData (*start)(ErlDrvPort port, char *command); + /* called when open_port/2 is invoked. + return value -1 means failure. */ +#else + ErlDrvData (*start)(ErlDrvPort port, char *command, SysDriverOpts* opts); + /* special options, only for system driver */ +#endif + void (*stop)(ErlDrvData drv_data); + /* called when port is closed, and when the + emulator is halted. */ + void (*output)(ErlDrvData drv_data, char *buf, int len); + /* called when we have output from erlang to + the port */ + void (*ready_input)(ErlDrvData drv_data, ErlDrvEvent event); + /* called when we have input from one of + the driver's handles) */ + void (*ready_output)(ErlDrvData drv_data, ErlDrvEvent event); + /* called when output is possible to one of + the driver's handles */ + char *driver_name; /* name supplied as command + in open_port XXX ? */ + void (*finish)(void); /* called before unloading the driver - + DYNAMIC DRIVERS ONLY */ + void *handle; /* Reserved -- Used by emulator internally */ + int (*control)(ErlDrvData drv_data, unsigned int command, char *buf, + int len, char **rbuf, int rlen); + /* "ioctl" for drivers - invoked by + 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 + to the port */ + void (*ready_async)(ErlDrvData drv_data, ErlDrvThreadData thread_data); + void (*flush)(ErlDrvData drv_data); + /* called when the port is about to be + closed, and there is data in the + driver queue that needs to be flushed + 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 + call into the driver. */ + void (*event)(ErlDrvData drv_data, ErlDrvEvent event, + ErlDrvEventData event_data); + /* Called when an event selected by + driver_event() has occurred */ + int extended_marker; /* ERL_DRV_EXTENDED_MARKER */ + int major_version; /* ERL_DRV_EXTENDED_MAJOR_VERSION */ + int minor_version; /* ERL_DRV_EXTENDED_MINOR_VERSION */ + int driver_flags; /* ERL_DRV_FLAGs */ + void *handle2; /* Reserved -- Used by emulator internally */ + void (*process_exit)(ErlDrvData drv_data, ErlDrvMonitor *monitor); + /* Called when a process monitor fires */ + void (*stop_select)(ErlDrvEvent event, void* reserved); + /* Called to close an event object */ + } ErlDrvEntry; + +

+ + int (*init)(void) + +

This is called directly after the driver has been loaded by + erl_ddll:load_driver/2. (Actually when the driver is + added to the driver list.) The driver should return 0, or if + the driver can't initialize, -1.

+ + int (*start)(ErlDrvPort port, char* command) + +

This is called when the driver is instantiated, when + open_port/2 is called. The driver should return a + number >= 0 or a pointer, or if the driver can't be started, + one of three error codes should be returned:

+

ERL_DRV_ERROR_GENERAL - general error, no error code

+

ERL_DRV_ERROR_ERRNO - error with error code in erl_errno

+

ERL_DRV_ERROR_BADARG - error, badarg

+

If an error code is returned, the port isn't started.

+ + void (*stop)(ErlDrvData drv_data) + +

This is called when the port is closed, with + port_close/1 or Port ! {self(), close}. Note + that terminating the port owner process also closes the + p\011 port.

+ + void (*output)(ErlDrvData drv_data, char *buf, int len) + +

This is called when an erlang process has sent data to the + port. The data is pointed to by buf, and is + len bytes. Data is sent to the port with Port ! {self(), {command, Data}}, or with + port_command/2. Depending on how the port was opened, + it should be either a list of integers 0...255 or a + binary. See open_port/3 and port_command/2.

+ + + void (*ready_input)(ErlDrvData drv_data, ErlDrvEvent event) + void (*ready_output)(ErlDrvData drv_data, ErlDrvEvent event) + +

This is called when a driver event (given in the + event parameter) is signaled. This is used to help + asynchronous drivers "wake up" when something happens.

+

On unix the event is a pipe or socket handle (or + something that the select system call understands).

+

On Windows the event is an Event or Semaphore (or + something that the WaitForMultipleObjects API + function understands). (Some trickery in the emulator allows + more than the built-in limit of 64 Events to be used.)

+

To use this with threads and asynchronous routines, create a + pipe on unix and an Event on Windows. When the routine + completes, write to the pipe (use SetEvent on + Windows), this will make the emulator call + ready_input or ready_output.

+ + char *driver_name + +

This is the name of the driver, it must correspond to the + atom used in open_port, and the name of the driver + library file (without the extension).

+ + void (*finish)(void) + +

This function is called by the erl_ddll driver when the + driver is unloaded. (It is only called in dynamic drivers.)

+

The driver is only unloaded as a result of calling + unload_driver/1, or when the emulator halts.

+ + void *handle + +

This field is reserved for the emulators internal use. The + emulator will modify this field; therefore, it is important + that the driver_entry isn't declared const.

+ + int (*control)(ErlDrvData drv_data, unsigned int command, char *buf, int len, char **rbuf, int rlen) + +

This is a special routine invoked with the erlang function + port_control/3. It works a little like an "ioctl" for + erlang drivers. The data given to port_control/3 + arrives in buf and len. The driver may send + data back, using *rbuf and rlen.

+

This is the fastest way of calling a driver and get a + response. It won't make any context switch in the erlang + emulator, and requires no message passing. It is suitable + for calling C function to get faster execution, when erlang + is too slow.

+

If the driver wants to return data, it should return it in + rbuf. When control is called, + *rbuf points to a default buffer of rlen bytes, which + can be used to return data. Data is returned different depending on + the port control flags (those that are set with + set_port_control_flags). +

+

If the flag is set to PORT_CONTROL_FLAG_BINARY, + a binary will be returned. Small binaries can be returned by writing + the raw data into the default buffer. A binary can also be + returned by setting *rbuf to point to a binary allocated with + driver_alloc_binary. + This binary will be freed automatically after control has returned. + The driver can retain the binary for read only access with + driver_binary_inc_refc to be freed later with + driver_free_binary. + It is never allowed to alter the binary after control has returned. + If *rbuf is set to NULL, an empty list will be returned. +

+

If the flag is set to 0, data is returned as a + list of integers. Either use the default buffer or set + *rbuf to point to a larger buffer allocated with + driver_alloc. + The buffer will be freed automatically after control has returned.

+

Using binaries is faster if more than a few bytes are returned.

+

The return value is the number of bytes returned in + *rbuf.

+ + + void (*timeout)(ErlDrvData drv_data) + +

This function is called any time after the driver's timer + reaches 0. The timer is activated with + driver_set_timer. There are no priorities or ordering + among drivers, so if several drivers time out at the same + time, any one of them is called first.

+ + + void (*outputv)(ErlDrvData drv_data, ErlIOVec *ev) + +

This function is called whenever the port is written to. If + it is NULL, the output function is called + instead. This function is faster than output, because + it takes an ErlIOVec directly, which requires no + copying of the data. The port should be in binary mode, see + open_port/2.

+

The ErlIOVec contains both a SysIOVec, + suitable for writev, and one or more binaries. If + these binaries should be retained, when the driver returns + from outputv, they can be queued (using driver_enq_bin + for instance), or if they are kept in a static or global + variable, the reference counter can be incremented.

+ + void (*ready_async)(ErlDrvData drv_data, ErlDrvThreadData thread_data) + +

This function is called after an asynchronous call has + completed. The asynchronous call is started with driver_async. + This function is called from the erlang emulator thread, as + opposed to the asynchronous function, which is called in + some thread (if multithreading is enabled).

+ + int (*call)(ErlDrvData drv_data, unsigned int command, char *buf, int len, char **rbuf, int rlen, unsigned int *flags) + +

This function is called from erlang:port_call/3. It + works a lot like the control call-back, but uses the + external term format for input and output.

+

command is an integer, obtained from the call from + erlang (the second argument to erlang:port_call/3).

+

buf and len provide the arguments to the call + (the third argument to erlang:port_call/3). They can + be decoded using ei functions.

+

rbuf points to a return buffer, rlen bytes + long. The return data should be a valid erlang term in the + external (binary) format. This is converted to an erlang + term and returned by erlang:port_call/3 to the + caller. If more space than rlen bytes is needed to + return data, *rbuf can be set to memory allocated with + driver_alloc. This memory will be freed automatically + after call has returned.

+

The return value is the number of bytes returned in + *rbuf. If ERL_DRV_ERROR_GENERAL is returned + (or in fact, anything < 0), erlang:port_call/3 will + throw a BAD_ARG.

+ + void (*event)(ErlDrvData drv_data, ErlDrvEvent event, ErlDrvEventData event_data) + +

Intentionally left undocumented.

+ + int extended_marker + +

+ This field should either be equal to ERL_DRV_EXTENDED_MARKER + or 0. An old driver (not aware of the extended driver + interface) should set this field to 0. If this field is + equal to 0, all the fields following this field also + have to be 0, or NULL in case it is a + pointer field. +

+ + int major_version + +

This field should equal ERL_DRV_EXTENDED_MAJOR_VERSION if + the extended_marker field equals + ERL_DRV_EXTENDED_MARKER.

+ + int minor_version + +

+ This field should equal ERL_DRV_EXTENDED_MINOR_VERSION if + the extended_marker field equals + ERL_DRV_EXTENDED_MARKER. +

+ + + int driver_flags + +

This field is used to pass driver capability information to the + runtime system. If the extended_marker field equals + ERL_DRV_EXTENDED_MARKER, it should contain 0 or + driver flags (ERL_DRV_FLAG_*) ored bitwise. Currently + the following driver flags exist: +

+ + ERL_DRV_FLAG_USE_PORT_LOCKING + + The runtime system will use port level locking on + all ports executing this driver instead of driver + level locking when the driver is run in a runtime + system with SMP support. For more information see the + erl_driver + documentation. + + ERL_DRV_FLAG_SOFT_BUSY + + Marks that driver instances can handle being called + in the output and/or + outputv callbacks even + though a driver instance has marked itself as busy (see + set_busy_port()). + Since erts version 5.7.4 this flag is required for drivers used + by the Erlang distribution (the behaviour has always been + required by drivers used by the distribution). + + + + void *handle2 + +

+ This field is reserved for the emulators internal use. The + emulator will modify this field; therefore, it is important + that the driver_entry isn't declared const. +

+ + void (*process_exit)(ErlDrvData drv_data, ErlDrvMonitor *monitor) + +

This callback is called when a monitored process exits. The + drv_data is the data associated with the port for which + the process is monitored (using driver_monitor_process) + and the monitor corresponds to the ErlDrvMonitor + structure filled + in when creating the monitor. The driver interface function + driver_get_monitored_process + can be used to retrieve the process id of the exiting process as + an ErlDrvTermData.

+ + void (*stop_select)(ErlDrvEvent event, void* reserved) + +

This function is called on behalf of + driver_select + when it is safe to close an event object.

+

A typical implementation on Unix is to do + close((int)event).

+

Argument reserved is intended for future use and should be ignored.

+

In contrast to most of the other call-back functions, + stop_select is called independent of any port. No + ErlDrvData argument is passed to the function. No + driver lock or port lock is guaranteed to be held. The port that + called driver_select might even be closed at the + time stop_select is called. But it could also be + the case that stop_select is called directly by + driver_select.

+

It is not allowed to call any functions in the + driver API from + stop_select. This strict limitation is due to the + volatile context that stop_select may be called.

+ + + + + + +
+ +
+ SEE ALSO +

erl_driver(3), + erl_ddll(3), + erlang(3), + kernel(3)

+
+ + diff --git a/erts/doc/src/epmd.xml b/erts/doc/src/epmd.xml new file mode 100644 index 0000000000..796ab3820b --- /dev/null +++ b/erts/doc/src/epmd.xml @@ -0,0 +1,120 @@ + + + + +
+ + 19962009 + Ericsson AB. 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. + + + + epmd + Claes Wikström + + 1 + + + 98-01-05 + A + epmd.xml +
+ epmd + Erlang Port Mapper Daemon + +

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 + OS kernel. + The name and the address are sent to the + daemon running on the local host. + In a TCP/IP environment, the address consists + of the IP address and a port number. The name of the node is + an atom on the form of . + The job of the daemon is to keep track of which + node name listens on which address. Hence, map + symbolic node names to machine addresses.

+

The daemon is started automatically by the Erlang start-up script.

+

The program can also be used for a variety of other + purposes, for example checking the DNS (Domain Name System) + configuration of a host.

+ + + + epmd [-daemon] + Start a name server as a daemon + +

Starts a name server as a daemon. If it has no argument, the + runs as a normal program with the controlling terminal + of the shell in which it is started. Normally, it should run as a + daemon.

+ + + + epmd -names + Request the names of the registered Erlang nodes on this host + +

Requests the names of the local Erlang nodes has + registered.

+ + + + epmd -kill + Kill the process + +

Kills the process.

+ + + + epmd -help + List options + +

Write short info about the usage including some debugging + options not listed here.

+ + + + +
+ + Environment variables + + + +

This environment variable can contain the port number epmd will use. + The default port will work fine in most cases. A different port can + be specified to allow several instances of epmd, representing + independent clusters of nodes, to co-exist on the same host. + All nodes in a cluster must use the same epmd port number.

+ + +
+ +
+ Logging +

On some operating systems syslog will be used for + error reporting when epmd runs as an daemon. To enable + the error logging you have to edit /etc/syslog.conf + file and add an entry

+ /var/log/epmd.log + ]]> +

where <TABs> are at least one real tab character. Spaces will + silently be ignored. +

+
+ + diff --git a/erts/doc/src/erl.xml b/erts/doc/src/erl.xml new file mode 100644 index 0000000000..90a3c53a37 --- /dev/null +++ b/erts/doc/src/erl.xml @@ -0,0 +1,928 @@ + + + + +
+ + 19962009 + Ericsson AB. 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. + + + + erl + + + + + erl.xml +
+ erl + The Erlang Emulator + +

The program starts an Erlang runtime system. + The exact details (for example, whether is a script or + a program and which other programs it calls) are system-dependent.

+

Windows users probably wants to use the program + instead, which runs in its own window with scrollbars and supports + command-line editing. The program on Windows provides + no line editing in its shell, and on Windows 95 there is no way + to scroll back to text which has scrolled off the screen. + The program must be used, however, in pipelines or if + you want to redirect standard input or output.

+ + + + erl <arguments> + Start an Erlang runtime system + +

Starts an Erlang runtime system.

+

The arguments can be divided into emulator flags, + flags and plain arguments:

+ + +

Any argument starting with the character is + interpreted as an emulator flag.

+

As indicated by the name, emulator flags controls + the behavior of the emulator.

+ + +

Any argument starting with the character + (hyphen) is interpreted as a + flag which should + be passed to the Erlang part of the runtime system, more + specifically to the system process, see + init(3).

+

The process itself interprets some of these + flags, the init flags. It also stores any + remaining flags, the user flags. The latter can + be retrieved by calling .

+

It can be noted that there are a small number of "-" + flags which now actually are emulator flags, see + the description below.

+ + +

Plain arguments are not interpreted in any way. They are + also stored by the process and can be + retrieved by calling . + Plain arguments can occur before the first flag, or after + a flag. Additionally, the flag + causes everything that follows to become plain arguments.

+ + +

Example:

+ 
+% erl +W w -sname arnie +R 9 -s my_init -extra +bertie
+(arnie@host)1> init:get_argument(sname).
+{ok,[["arnie"]]}
+(arnie@host)2> init:get_plain_arguments().
+["+bertie"]
+

Here and are emulator flags. + is an init flag, interpreted by . + is a user flag, stored by . + It is read by Kernel and will cause the Erlang runtime system + to become distributed. Finally, everything after + (that is, ) is considered as plain arguments.

+ 
+% erl -myflag 1
+1> init:get_argument(myflag).
+{ok,[["1"]]}
+2> init:get_plain_arguments().
+[]
+

Here the user flag is passed to and stored + by the process. It is a user defined flag, + presumably used by some user defined application.

+ + + + +
+ + Flags +

In the following list, init flags are marked (init flag). + Unless otherwise specified, all other flags are user flags, for + which the values can be retrieved by calling + . Note that the list of user flags is + not exhaustive, there may be additional, application specific + flags which instead are documented in the corresponding + application documentation.

+ + (init flag) + +

Everything following up to the next flag + ( or ) is considered plain arguments + and can be retrieved using .

+ + + +

Sets the application configuration parameter to + the value for the application , + see app(4) and + application(3).

+ + + + +

Command line arguments are read from the file . + The arguments read from the file replace the + '' flag on the resulting command line.

+

The file should be a plain text file and may + contain comments and command line arguments. A comment begins + with a # character and continues until next end of line character. + Backslash (\\) is used as quoting character. All command line + arguments accepted by are allowed, also the + flag. Be careful not to cause circular + dependencies between files containing the flag, + though.

+

The flag is treated specially. Its scope ends + at the end of the file. Arguments following an + flag are moved on the command line into the section, + i.e. the end of the command line following after an + flag.

+ + + +

The initial Erlang shell does not read user input until + the system boot procedure has been completed (Erlang 5.4 and + later). This flag disables the start synchronization feature + and lets the shell start in parallel with the rest of + the system.

+ + + +

Specifies the name of the boot file, , + which is used to start the system. See + init(3). Unless + contains an absolute path, the system searches + for in the current and + directories.

+

Defaults to .

+ + + +

If the boot script contains a path variable other + than , this variable is expanded to . + Used when applications are installed in another directory + than , see + systools:make_script/1,2.

+ + + +

Enables the code path cache of the code server, see + code(3).

+ + + +

Compiles the specified modules and then terminates (with + non-zero exit code if the compilation of some file did not + succeed). Implies . Not recommended - use + erlc instead.

+ + + +

Specifies the name of a configuration file, + , which is used to configure + applications. See + app(4) and + application(3).

+ + + + +

If this flag is present, will not maintain a + fully connected network of distributed Erlang nodes, and then + global name registration cannot be used. See + global(3).

+ + + +

Obsolete flag without any effect and common misspelling for + . Use instead.

+ + + +

Starts the Erlang runtime system detached from the system + console. Useful for running daemons and backgrounds processes.

+ + + +

Useful for debugging. Prints out the actual arguments + sent to the emulator.

+ + + +

Sets the host OS environment variable to + the value for the Erlang runtime system. + Example:

+ 
+% erl -env DISPLAY gin:0
+

In this example, an Erlang runtime system is started with + the environment variable set to .

+ + (init flag) + +

Makes evaluate the expression , see + init(3).

+ + (init flag) + +

Everything following is considered plain + arguments and can be retrieved using + .

+ + + +

Starts heart beat monitoring of the Erlang runtime system. + See heart(3).

+ + + +

Starts the Erlang runtime system as a hidden node, if it is + run as a distributed node. Hidden nodes always establish + hidden connections to all other nodes except for nodes in the + same global group. Hidden connections are not published on + neither of the connected nodes, i.e. neither of the connected + nodes are part of the result from on the other + node. See also hidden global groups, + global_group(3).

+ + + +

Specifies the IP addresses for the hosts on which Erlang + boot servers are running, see + erl_boot_server(3). + This flag is mandatory if the flag is + present.

+

The IP addresses must be given in the standard form (four + decimal numbers separated by periods, for example + . Hosts names are not acceptable, but + a broadcast address (preferably limited to the local network) + is.

+ + + +

Specifies the identity of the Erlang runtime system. If it is + run as a distributed node, must be identical to + the name supplied together with the or + flag.

+ + + +

Makes write some debug information while + interpreting the boot script.

+ + (emulator flag) + + +

Selects an instrumented Erlang runtime system (virtual + machine) to run, instead of the ordinary one. When running an + instrumented runtime system, some resource usage data can be + obtained and analysed using the module . + Functionally, it behaves exactly like an ordinary Erlang + runtime system.

+ + + +

Specifies the method used by to load + Erlang modules into the system. See + erl_prim_loader(3). + Two methods are supported, and + . means use the local file system, + this is the default. means use a boot server on + another machine, and the , and + flags must be specified as well. If + is something else, the user supplied + port program is started.

+ + + +

Makes the Erlang runtime system invoke in + the current working directory and then terminate. See + make(3). Implies + .

+ + + +

Displays the manual page for the Erlang module . + Only supported on Unix.

+ + + +

Indicates if the system should load code dynamically + (), or if all code should be loaded + during system initialization (), see + code(3). Defaults to + .

+ + + +

Makes the Erlang runtime system into a distributed node. + This flag invokes all network servers necessary for a node to + become distributed. See + net_kernel(3). + It is also ensured that runs on the current host + before Erlang is started. See + epmd(1).

+

The name of the node will be , where + is the fully qualified host name of the current + host. For short names, use the flag instead.

+ + + +

Ensures that the Erlang runtime system never tries to read + any input. Implies .

+ + + +

Starts an Erlang runtime system with no shell. This flag + makes it possible to have the Erlang runtime system as a + component in a series of UNIX pipes.

+ + + +

Disables the sticky directory facility of the Erlang code + server, see + code(3).

+ + + +

Invokes the old Erlang shell from Erlang 3.3. The old shell + can still be used.

+ + + +

Adds the specified directories to the beginning of the code + path, similar to . See + code(3). + As an alternative to -pa, if several directories are + to be prepended to the code and the directories have a + common parent directory, that parent directory could be + specified in the ERL_LIBS environment variable. + See code(3).

+ + + +

Adds the specified directories to the end of the code path, + similar to . See + code(3).

+ + + +

Starts Erlang with a remote shell connected to .

+ + + +

Specifies an alternative to for starting a slave + node on a remote host. See + slave(3).

+ + (init flag) + +

Makes call the specified function. + defaults to . If no arguments are provided, + the function is assumed to be of arity 0. Otherwise it is + assumed to be of arity 1, taking the list + as argument. All arguments are passed + as strings. See + init(3).

+ + (init flag) + +

Makes call the specified function. + defaults to . If no arguments are provided, + the function is assumed to be of arity 0. Otherwise it is + assumed to be of arity 1, taking the list + as argument. All arguments are passed + as atoms. See + init(3).

+ + + +

Sets the magic cookie of the node to , see + erlang:set_cookie/2.

+ + + +

Specifies how long time (in milliseconds) the + process is allowed to spend shutting down the system. If + ms have elapsed, all processes still existing are + killed. Defaults to .

+ + + +

Makes the Erlang runtime system into a distributed node, + similar to , but the host name portion of the node + name will be the short name, not fully + qualified.

+

This is sometimes the only way to run distributed Erlang if + the DNS (Domain Name System) is not running. There can be no + communication between nodes running with the + flag and those running with the flag, as node + names must be unique in distributed Erlang systems.

+ + + + +

-smp enable and -smp starts the Erlang runtime + system with SMP support enabled. This may fail if no runtime + system with SMP support is available. -smp auto starts + the Erlang runtime system with SMP support enabled if it is + available and more than one logical processor are detected. + -smp disable starts a runtime system without SMP support. + By default -smp auto will be used unless a conflicting + parameter has been passed, then -smp disable will be + used. Currently only the -hybrid parameter conflicts + with -smp auto.

+

NOTE: The runtime system with SMP support will not + be available on all supported platforms. See also the + +S flag.

+ + (emulator flag) + +

Makes the emulator print out its version number. The same + as .

+ + +
+ +
+ + Emulator Flags +

invokes the code for the Erlang emulator (virtual + machine), which supports the following flags:

+ + + + +

Suggested stack size, in kilowords, for threads in the + async-thread pool. Valid range is 16-8192 kilowords. The + default suggested stack size is 16 kilowords, i.e, 64 + kilobyte on 32-bit architectures. This small default size + has been chosen since the amount of async-threads might + be quite large. The default size is enough for drivers + delivered with Erlang/OTP, but might not be sufficiently + large for other dynamically linked in drivers that use the + driver_async() + functionality. Note that the value passed is only a + suggestion, and it might even be ignored on some + platforms.

+ + + + +

Sets the number of threads in async thread pool, valid range + is 0-1024. Default is 0.

+ + + +

The option makes interrupt the current + shell instead of invoking the emulator break handler. + The option (same as specifying without an + extra option) disables the break handler. The option + makes the emulator ignore any break signal.

+

If the option is used with on Unix, + will restart the shell process rather than + interrupt it.

+

Note that on Windows, this flag is only applicable for + , not (). Note also that + is used instead of on Windows.

+ + + +

Disable compensation for sudden changes of system time.

+

Normally, will not immediately reflect + sudden changes in the system time, in order to keep timers + (including ) working. Instead, the time + maintained by is slowly adjusted towards + the new system time. (Slowly means in one percent adjustments; + if the time is off by one minute, the time will be adjusted + in 100 minutes.)

+

When the option is given, this slow adjustment + will not take place. Instead will always + reflect the current system time. Note that timers are based + on . If the system time jumps, timers + then time out at the wrong time.

+ + + +

If the emulator detects an internal error (or runs out of memory), + it will by default generate both a crash dump and a core dump. + The core dump will, however, not be very useful since the content + of process heaps is destroyed by the crash dump generation.

+ +

The +d option instructs the emulator to only produce a + core dump and no crash dump if an internal error is detected.

+ +

Calling erlang:halt/1 with a string argument will still + produce a crash dump.

+ + + +

Sets the default heap size of processes to the size + .

+ + + +

Enables or disables the kernel poll functionality if + the emulator supports it. Default is (disabled). + If the emulator does not support kernel poll, and + the flag is passed to the emulator, a warning is + issued at startup.

+ + + +

Enables auto load tracing, displaying info while loading + code.

+ + + + +

Memory allocator specific flags, see + erts_alloc(3) for + further information.

+ + + + +

Sets the maximum number of concurrent processes for this + system. must be in the range 16..134217727. + Default is 32768.

+ + + + +

Sets the compatibility mode.

+

The distribution mechanism is not backwards compatible by + default. This flags sets the emulator in compatibility mode + with an earlier Erlang/OTP release . + The release number must be in the range + ]]>. This limits the emulator, + making it possible for it to communicate with Erlang nodes + (as well as C- and Java nodes) running that earlier release.

+

For example, an R10 node is not automatically compatible + with an R9 node, but R10 nodes started with the + flag can co-exist with R9 nodes in the same distributed + Erlang system, they are R9-compatible.

+

Note: Make sure all nodes (Erlang-, C-, and Java nodes) of + a distributed Erlang system is of the same Erlang/OTP release, + or from two different Erlang/OTP releases X and Y, where + all Y nodes have compatibility mode X.

+

For example: A distributed Erlang system can consist of + R10 nodes, or of R9 nodes and R9-compatible R10 nodes, but + not of R9 nodes, R9-compatible R10 nodes and "regular" R10 + nodes, as R9 and "regular" R10 nodes are not compatible.

+ + + +

Force ets memory block to be moved on realloc.

+ + + + +

Sets the amount of scheduler threads to create and scheduler + threads to set online when SMP support has been enabled. + Valid range for both values are 1-1024. If the + Erlang runtime system is able to determine the amount + of logical processors configured and logical processors available, + Schedulers will default to logical processors configured, + and SchedulersOnline will default to logical processors + available; otherwise, the default values will be 1. Schedulers + may be omitted if :SchedulerOnline is not and vice versa. The + amount of schedulers online can be changed at run time via + erlang:system_flag(schedulers_online, SchedulersOnline). +

+

This flag will be ignored if the emulator doesn't have + SMP support enabled (see the -smp + flag).

+ + + +

Scheduling specific flags.

+ + +sbt BindType + + +

Set scheduler bind type. Currently valid BindTypes: +

+ + u +

Same as + erlang:system_flag(scheduler_bind_type, unbound). +

+ ns +

Same as + erlang:system_flag(scheduler_bind_type, no_spread). +

+ ts +

Same as + erlang:system_flag(scheduler_bind_type, thread_spread). +

+ ps +

Same as + erlang:system_flag(scheduler_bind_type, processor_spread). +

+ s +

Same as + erlang:system_flag(scheduler_bind_type, spread). +

+ nnts +

Same as + erlang:system_flag(scheduler_bind_type, no_node_thread_spread). +

+ nnps +

Same as + erlang:system_flag(scheduler_bind_type, no_node_processor_spread). +

+ tnnps +

Same as + erlang:system_flag(scheduler_bind_type, thread_no_node_processor_spread). +

+ db +

Same as + erlang:system_flag(scheduler_bind_type, default_bind). +

+ +

Binding of schedulers are currently only supported on newer + Linux and Solaris systems.

+

If no CPU topology is available when the +sbt flag + is processed and BindType is any other type than + u, the runtime system will fail to start. CPU + topology can be defined using the + +sct flag. Note + that the +sct flag may have to be passed before the + +sbt flag on the command line (in case no CPU topology + has been automatically detected).

+

For more information, see + erlang:system_flag(scheduler_bind_type, SchedulerBindType). +

+ + +sct CpuTopology + + + + = integer(); when 0 =< =< 65535]]> + = -]]> + = | ]]> + = , | ]]> + = L]]> + = T | t]]> + = C | c]]> + = P | p]]> + = N | n]]> + = | ]]> + : | ]]> + +

Upper-case letters signify real identifiers and lower-case + letters signify fake identifiers only used for description + of the topology. Identifiers passed as real identifiers may + be used by the runtime system when trying to access specific + hardware and if they are not correct the behavior is + undefined. Faked logical CPU identifiers are not accepted + since there is no point in defining the CPU topology without + real logical CPU identifiers. Thread, core, processor, and + node identifiers may be left out. If left out, thread id + defaults to t0, core id defaults to c0, + processor id defaults to p0, and node id will + be left undefined. Either each logical processor must + belong to one and only one NUMA node, or no logical + processors must belong to any NUMA nodes. +

+

Both increasing and decreasing ]]>s + are allowed.

+

NUMA node identifiers are system wide. That is, each NUMA + node on the system have to have a unique identifier. Processor + identifiers are also system wide. Core identifiers are + processor wide. Thread identifiers are core wide.

+

The order of the identifier types imply the hierarchy of the + CPU topology. Valid orders are either + ]]>, + or + ]]>. + That is, thread is part of a core which is part of a processor + which is part of a NUMA node, or thread is part of a core which + is part of a NUMA node which is part of a processor. A cpu + topology can consist of both processor external, and processor + internal NUMA nodes as long as each logical processor belongs + to one and only one NUMA node. If ]]> + is left out, its default position will be before + ]]>. That is, the default is + processor external NUMA nodes. +

+

If a list of identifiers is used in an + ]]>:

+ + ]]> have to be a list + of identifiers. + At least one other identifier type apart from + ]]> also have to have a + list of identifiers. + All lists of identifiers have to produce the + same amount of identifiers. + +

A simple example. A single quad core processor may be + described this way:

+
+% erl +sct L0-3c0-3
+1> erlang:system_info(cpu_topology).
+[{processor,[{core,{logical,0}},
+             {core,{logical,1}},
+             {core,{logical,2}},
+             {core,{logical,3}}]}]
+
+

A little more complicated example. Two quad core + processors. Each processor in its own NUMA node. + The ordering of logical processors is a little weird. + This in order to give a better example of identifier + lists:

+
+% erl +sct L0-1,3-2c0-3p0N0:L7,4,6-5c0-3p1N1
+1> erlang:system_info(cpu_topology).
+[{node,[{processor,[{core,{logical,0}},
+                    {core,{logical,1}},
+                    {core,{logical,3}},
+                    {core,{logical,2}}]}]},
+ {node,[{processor,[{core,{logical,7}},
+                    {core,{logical,4}},
+                    {core,{logical,6}},
+                    {core,{logical,5}}]}]}]
+
+

As long as real identifiers are correct it is okay + to pass a CPU topology that is not a correct + description of the CPU topology. When used with + care this can actually be very useful. This in + order to trick the emulator to bind its schedulers + as you want. For example, if you want to run multiple + Erlang runtime systems on the same machine, you + want to reduce the amount of schedulers used and + manipulate the CPU topology so that they bind to + different logical CPUs. An example, with two Erlang + runtime systems on a quad core machine:

+
+% erl +sct L0-3c0-3 +sbt db +S3:2 -detached -noinput -noshell -sname one
+% erl +sct L3-0c0-3 +sbt db +S3:2 -detached -noinput -noshell -sname two
+
+

In this example each runtime system have two + schedulers each online, and all schedulers online + will run on different cores. If we change to one + scheduler online on one runtime system, and three + schedulers online on the other, all schedulers + online will still run on different cores.

+

Note that a faked CPU topology that does not reflect + how the real CPU topology looks like is likely to + decrease the performance of the runtime system.

+

For more information, see + erlang:system_flag(cpu_topology, CpuTopology).

+ + + + + + +

Suggested stack size, in kilowords, for scheduler threads. + Valid range is 4-8192 kilowords. The default stack size + is OS dependent.

+ + + + +

Enables modified timing and sets the modified timing level. + Currently valid range is 0-9. The timing of the runtime system + will change. A high level usually means a greater change than + a low level. Changing the timing can be very useful for finding + timing related bugs.

+

Currently, modified timing affects the following:

+ + Process spawning + +

A process calling , , + , or will be scheduled + out immediately after completing the call. When higher modified + timing levels are used, the caller will also sleep for a while + after being scheduled out.

+ + Context reductions + The amount of reductions a process is a allowed to + use before being scheduled out is increased or reduced. + Input reductions + The amount of reductions performed before checking I/O + is increased or reduced. + +

NOTE: Performance will suffer when modified timing + is enabled. This flag is only intended for testing and + debugging. Also note that and + trace messages will be lost when tracing on the spawn BIFs. This + flag may be removed or changed at any time without prior notice.

+ + + +

Makes the emulator print out its version number.

+ + + +

Verbose.

+ + + +

Sets the mapping of warning messages for . + Messages sent to the error logger using one of the warning + routines can be mapped either to errors (default), warnings + (), or info reports (). The current + mapping can be retrieved using + . See + error_logger(3) + for further information.

+ + +
+ +
+ + Environment variables + + + +

If the emulator needs to write a crash dump, the value of this + variable will be the file name of the crash dump file. + If the variable is not set, the name of the crash dump file will + be in the current directory.

+ + + +

Unix systems: If the emulator needs to write a crash dump, + it will use the value of this variable to set the nice value + for the process, thus lowering its priority. The allowable range is + 1 through 39 (higher values will be replaced with 39). The highest + value, 39, will give the process the lowest priority.

+ + + +

Unix systems: This variable gives the number of seconds that + the emulator will be allowed to spend writing a crash dump. When + the given number of seconds have elapsed, the emulator will be + terminated by a SIGALRM signal.

+ + + +

The content of this environment variable will be added to the + beginning of the command line for .

+

The flag is treated specially. Its scope ends + at the end of the environment variable content. Arguments + following an flag are moved on the command line into + the section, i.e. the end of the command line + following after an flag.

+ + and + +

The content of these environment variables will be added to the + end of the command line for .

+

The flag is treated specially. Its scope ends + at the end of the environment variable content. Arguments + following an flag are moved on the command line into + the section, i.e. the end of the command line + following after an flag.

+ + + +

This environment variable contains a list of additional library + directories that the code server will search for applications and + add to the code path. + See code(3).

+ + + +

This environment variable can contain the port number to use when + communicating with epmd. The default + port will work fine in most cases. A different port can be specified + to allow nodes of independent clusters to co-exist on the same host. + All nodes in a cluster must use the same epmd port number.

+ + +
+ +
+ SEE ALSO +

init(3), + erl_prim_loader(3), + erl_boot_server(3), + code(3), + application(3), + heart(3), + net_kernel(3), + auth(3), + make(3), + epmd(1), + erts_alloc(3)

+
+ + diff --git a/erts/doc/src/erl_dist_protocol.xml b/erts/doc/src/erl_dist_protocol.xml new file mode 100644 index 0000000000..9a203289e9 --- /dev/null +++ b/erts/doc/src/erl_dist_protocol.xml @@ -0,0 +1,802 @@ + + + + +
+ + 2007 + 2007 + Ericsson AB, 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. + + The Initial Developer of the Original Code is Ericsson AB. + + + Distribution Protocol + + + 2007-09-21 + PA1 + erl_dist_protocol.xml +
+ +

+The description here is far from complete and will therefore be further +refined in upcoming releases. + +The protocols both from Erlang nodes towards +EPMD (Erlang Port Mapper Daemon) and between Erlang nodes, however, are +stable since many years. +

+ +

The distribution protocol can be divided into four (4) parts:

+ + +

+ 1. Low level socket connection. +

+ + + 2. Handshake, interchange node name and authenticate. + + + 3. Authentication (done by net_kernel). + + + 4. Connected. + + +

+ A node fetches the Port number of another node through the EPMD (at the + other host) in order to initiate a connection request. +

+

+For each host where a distributed Erlang node is running there should also +be an EPMD running. The EPMD can be started explicitly or automatically +as a result of the Erlang node startup. +

+

+By default EPMD listens on port 4369. +

+

+ 3 and 4 are performed at the same level but the net_kernel disconnects the + other node if it communicates using an invalid cookie (after one (1) second). +

+ +

The integers in all multi-byte fields are in big-endian order.

+ +
+ EPMD Protocol +

+ The requests served by the EPMD (Erlang Port Mapper Daemon) are + summarized in the figure below. +

+ + + + Summary of EPMD requests. + + +

+ Each request *_REQ is preceded by a two-byte length field. + Thus, the overall request format is: +

+ + + + 2 + n + + + Length + Request + +
+ +
+ Register a node in the EPMD +

+ When a distributed node is started it registers itself in EPMD. + The message ALIVE2_REQ described below is sent from the node towards + EPMD. The response from EPMD is ALIVE2_RESP. +

+ + + 1 + 2 + 1 + 1 + 2 + 2 + 2 + Nlen + 2 + Elen + + + 120 + PortNo + NodeType + Protocol + LowestVersion + HighestVersion + Nlen + NodeName + Elen + Extra + + ALIVE2_REQ (120)
+ + PortNo + + The port number on which the node accept connection requests. + + NodeType + + 77 = normal Erlang node, 72 = hidden node (C-node),... + + Protocol + + 0 = tcp/ip-v4, ... + + LowestVersion + + The lowest distribution version that this node can handle. + See the next field for possible values. + + HighestVersion + + The highest distribution version that this node can handle. + The value in R6B and later is 5. + + Nlen + + The length of the NodeName. + + NodeName + + The NodeName as a string of length Nlen. + + Elen + + The length of the Extra field. + + Extra + + Extra field of Elen bytes. + + +

+ The connection created to the EPMD must be kept as long as the + node is a distributed node. When the connection is closed + the node is automatically unregistered from the EPMD. +

+

+ The response message ALIVE2_RESP is described below. +

+ + + + 1 + 1 + 2 + + + 121 + Result + Creation + + ALIVE2_RESP (121)
+

+ Result = 0 -> ok, Result > 0 -> error +

+
+ +
+ Unregister a node from the EPMD +

+ A node unregister itself from the EPMD by simply closing the + TCP connection towards EPMD established when the node was registered. +

+
+ +
+ Get the distribution port of another node +

+ When one node wants to connect to another node it starts with + a PORT_PLEASE2_REQ request towards EPMD on the host where the + node resides in order to get the distribution port that the node + listens to. +

+ + + + 1 + N + + + 122 + NodeName + + PORT_PLEASE2_REQ (122)
+

+ where N = Length - 1 +

+ +

+

+ + + 1 + 1 + + + 119 + Result + + + PORT2_RESP (119) response indicating error, Result > 0. + +
+

Or

+ + + 1 + 1 + 2 + 1 + 1 + 2 + 2 + 2 + Nlen + 2 + Elen + + + 119 + Result + PortNo + NodeType + Protocol + HighestVersion + LowestVersion + Nlen + NodeName + Elen + Extra + + PORT2_RESP when Result = 0.
+

+If Result > 0, the packet only consists of [119, Result]. +

+ +

EPMD will close the socket as soon as it has sent the information.

+
+ +
+ Get all registered names from EPMD +

+ This request is used via the Erlang function + net_adm:names/1,2. A TCP connection is opened + towards EPMD and this request is sent. +

+ + + 1 + + + 110 + + NAMES_REQ (110)
+ + +

The response for a NAMES_REQ looks like this:

+ + + 4 +   + + + EPMDPortNo + NodeInfo* + + NAMES_RESP
+

+ NodeInfo is a string written for each active node. + When all NodeInfo has been written the connection is + closed by EPMD. +

+

+ NodeInfo is, as expressed in Erlang: +

+ + io:format("name ~s at port ~p~n", [NodeName, Port]). + +
+ + +
+ Dump all data from EPMD +

+ This request is not really used, it should be regarded as a debug + feature. +

+ + + 1 + + + 100 + + DUMP_REQ
+ +

The response for a DUMP_REQ looks like this:

+ + + 4 +   + + + EPMDPortNo + NodeInfo* + + DUMP_RESP
+

+ NodeInfo is a string written for each node kept in EPMD. + When all NodeInfo has been written the connection is + closed by EPMD. +

+

+ NodeInfo is, as expressed in Erlang: +

+ + io:format("active name ~s at port ~p, fd = ~p ~n", + [NodeName, Port, Fd]). + +

+ or +

+ + io:format("old/unused name ~s at port ~p, fd = ~p~n", + [NodeName, Port, Fd]). + + +
+ +
+ Kill the EPMD +

+ This request will kill the running EPMD. It is almost never used. +

+ + + 1 + + + 107 + + KILL_REQ
+ +

The response fo a KILL_REQ looks like this:

+ + + 2 + + + OKString + + KILL_RESP
+

+ where OKString is "OK". +

+
+ +
+ STOP_REQ (Not Used) +

+ + + 1 + n + + + 115 + NodeName + + STOP_REQ
+

+ where n = Length - 1 +

+

+ The current implementation of Erlang does not care if the connection + to the EPMD is broken. +

+

The response for a STOP_REQ looks like this.

+ + + 7 + + + OKString + + STOP_RESP
+

+ where OKString is "STOPPED". +

+

A negative response can look like this.

+ + + 7 + + + NOKString + + STOP_NOTOK_RESP
+

+ where NOKString is "NOEXIST". +

+
+ + +
+ +
+ Handshake +

+ The handshake is discussed in detail in the internal documentation for + the kernel (Erlang) application. +

+
+ +
+ + Protocol between connected nodes +

+ As of erts version 5.7.2 the runtime system passes a distribution + flag in the handshake stage that enables the use of a + distribution + header on all messages passed. Messages passed between + nodes are in this case on the following format: +

+ + + 4 + d + n + m + + + Length + DistributionHeader + ControlMessage + Message + +
+

+ where: +

+

+ Length is equal to d + n + m +

+

+ ControlMessage is a tuple passed using the external format of + Erlang. +

+

+ Message is the message sent to another node using the '!' + (in external format). Note that Message is only passed in + combination with a ControlMessage encoding a send ('!'). +

+

+ Also note that the + version number is omitted from the terms that follow a + distribution header. +

+

+ Nodes with an erts version less than 5.7.2 does not pass the + distribution flag that enables the distribution header. Messages + passed between nodes are in this case on the following format: +

+ + + 4 + 1 + n + m + + + Length + Type + ControlMessage + Message + +
+

+ where: +

+

+ Length is equal to 1 + n + m +

+

+ Type is: 112 (pass through) +

+

+ ControlMessage is a tuple passed using the external format of + Erlang. +

+

+ Message is the message sent to another node using the '!' + (in external format). Note that Message is only passed in + combination with a ControlMessage encoding a send ('!'). +

+

+ The ControlMessage is a tuple, where the first element + indicates which distributed operation it encodes. +

+ + LINK + +

+ {1, FromPid, ToPid} +

+ + + SEND + +

+ {2, Cookie, ToPid} +

+

+ Note followed by Message +

+ + + EXIT + +

+ {3, FromPid, ToPid, Reason} +

+ + + UNLINK + +

+ {4, FromPid, ToPid} +

+ + + NODE_LINK + +

+ {5} +

+ + + REG_SEND + +

+ {6, FromPid, Cookie, ToName} +

+

+ Note followed by Message +

+ + + GROUP_LEADER + +

+ {7, FromPid, ToPid} +

+ + + EXIT2 + +

+ {8, FromPid, ToPid, Reason} +

+ + +
+ + +
+ New Ctrlmessages for distrvsn = 1 (OTP R4) + + SEND_TT + +

+ {12, Cookie, ToPid, TraceToken} +

+

+ Note followed by Message +

+ + + EXIT_TT + +

+ {13, FromPid, ToPid, TraceToken, Reason} +

+ + + REG_SEND_TT + +

+ {16, FromPid, Cookie, ToName, TraceToken} +

+

+ Note followed by Message +

+ + + EXIT2_TT + +

+ {18, FromPid, ToPid, TraceToken, Reason} +

+ + +
+ +
+ New Ctrlmessages for distrvsn = 2 +

+ distrvsn 2 was never used. +

+
+ +
+ New Ctrlmessages for distrvsn = 3 (OTP R5C) +

+ None, but the version number was increased anyway. +

+
+ +
+ New Ctrlmessages for distrvsn = 4 (OTP R6) +

+ These are only recognized by Erlang nodes, not by hidden nodes. +

+ + MONITOR_P + +

+ {19, FromPid, ToProc, Ref} + + FromPid = monitoring process + ToProc = monitored process pid or name (atom) +

+ + + DEMONITOR_P + +

+ {20, FromPid, ToProc, Ref} + We include the FromPid just in case we want to trace this. + + FromPid = monitoring process + ToProc = monitored process pid or name (atom) +

+ + + MONITOR_P_EXIT + +

+ {21, FromProc, ToPid, Ref, Reason} + + FromProc = monitored process pid or name (atom) + ToPid = monitoring process + Reason = exit reason for the monitored process +

+ + +
+ diff --git a/erts/doc/src/erl_driver.xml b/erts/doc/src/erl_driver.xml new file mode 100644 index 0000000000..0b11f4bbcb --- /dev/null +++ b/erts/doc/src/erl_driver.xml @@ -0,0 +1,2465 @@ + + + + +
+ + 20012009 + Ericsson AB. 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. + + + + erl_driver + Jakob Cederlund + Jakob Cederlund + 1 + + + 2000-11-27 + PA1 + erl_driver.xml +
+ erl_driver + API functions for an Erlang driver + +

As of erts version 5.5.3 the driver interface has been extended + (see extended marker). + The extended interface introduce + version management, + the possibility to pass capability flags + (see driver flags) + to the runtime system at driver initialization, and some new + driver API functions.

+ +

Old drivers (compiled with an erl_driver.h from an + earlier erts version than 5.5.3) have to be recompiled + (but does not have to use the extended interface).

+ +

The driver calls back to the emulator, using the API + functions declared in erl_driver.h. They are used for + outputting data from the driver, using timers, etc.

+

A driver is a library with a set of function that the emulator + calls, in response to Erlang functions and message + sending. There may be multiple instances of a driver, each + 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.

+

Most of the functions takes the port 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 + driver_entry).

+

Some of the functions takes a parameter of type + ErlDrvBinary, a driver binary. It should be both + allocated and freed by the caller. Using a binary directly avoid + one extra copying of data.

+

Many of the output functions has a "header buffer", with + hbuf and hlen 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 + the port. (Although in the latest versions of Erlang, there is + the binary syntax, that enables you to match on the beginning of + a binary.) + +

+

In the runtime system with SMP support, drivers are locked either + on driver level or port level (driver instance level). By default + driver level locking will be used, i.e., only one emulator thread + will execute code in the driver at a time. If port level locking + is used, multiple emulator threads may execute code in the driver + at the same time. There will only be one thread at a time calling + driver call-backs corresponding to the same port, though. In order + to enable port level locking set the ERL_DRV_FLAG_USE_PORT_LOCKING + driver flag in + the driver_entry + used by the driver. When port level locking is used it is the + responsibility of the driver writer to synchronize all accesses + to data shared by the ports (driver instances).

+

Most drivers written before the runtime system with SMP + support existed will be able to run in the runtime system + with SMP support without being rewritten if driver + level locking is used.

+ +

It is assumed that drivers does 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.

+ +

Previously, in the runtime system without SMP support, + specific driver call-backs were always called from the same + thread. This is not the case in the runtime system + with SMP support. Regardless of locking scheme used, calls + to driver call-backs may be made from different threads, e.g., + two consecutive calls to exactly the same call-back for exactly + the same port may be made from two different threads. This + will for most drivers not be a problem, but it might. + Drivers that depend on all call-backs being called in the + same thread, have to be rewritten before being used + in the runtime system with SMP support.

+ +

Regardless of locking scheme used, calls to driver + call-backs may be made from different threads.

+ +

Most functions in this API are not thread-safe, i.e., + they may not be called from an arbitrary thread. Function + 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 + these threads.

+ +

Functions not explicitly documented as thread-safe are + not thread-safe. Also note that some functions + are only thread safe when used in a runtime + system with SMP support.

+ + + +
+ FUNCTIONALITY +

All functions that a driver needs to do with Erlang are + performed through driver API functions. There are functions + for the following functionality:

+ + Timer functions + Timer functions are used to control the timer that a driver + may use. The timer will have the emulator call the + timeout entry + function after a specified time. Only one timer is available + for each driver instance. + Queue handling + +

Every driver instance has an associated queue. This queue is a + SysIOVec that works as a buffer. It's mostly used for + the driver to buffer data that should be written to a device, + it is a byte stream. If the port owner process closes the + driver, and the queue is not empty, the driver will not be + closed. This enables the driver to flush its buffers before + closing.

+

The queue can be manipulated from arbitrary threads if + a port data lock is used. See documentation of the + ErlDrvPDL type for + more information.

+ + Output functions + With the output functions, the driver sends data back + the emulator. They will be received as messages by the port owner + process, see open_port/2. The vector function and the + function taking a driver binary is faster, because that avoid + copying the data buffer. There is also a fast way of sending + terms from the driver, without going through the binary term + format. + Failure + The driver can exit and signal errors up to Erlang. This is + only for severe errors, when the driver can't possibly keep + open. + Asynchronous calls + The latest Erlang versions (R7B and later) has provision for + asynchronous function calls, using a thread pool provided by + Erlang. There is also a select call, that can be used for + asynchronous drivers. + Multi-threading + +

A POSIX thread like API for multi-threading is provided. The + Erlang driver thread API only provide a subset of the functionality + provided by the POSIX thread API. The subset provided is + more or less the basic functionality needed for multi-threaded + programming: +

+ + Threads + Mutexes + Condition variables + Read/Write locks + Thread specific data + +

The Erlang driver thread API can be used in conjunction with + the POSIX thread API on UN-ices and with the Windows native thread + API on Windows. The Erlang driver thread API has the advantage of + being portable, but there might exist situations where you want to + use functionality from the POSIX thread API or the Windows + native thread API. +

+

The Erlang driver thread API only return 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. +

+

Note that there exist no "condition variable wait with timeout" in + the Erlang driver thread API. This is due to issues with + pthread_cond_timedwait(). When the system clock suddenly + is changed, it isn't always guaranteed that you will wake up from + the call as expected. An Erlang runtime system has to be able to + cope with sudden changes of the system clock. Therefore, we have + omitted it from the Erlang driver thread API. In the Erlang driver + case, timeouts can and should be handled with the timer functionality + of the Erlang driver API. +

+

In order for the Erlang driver thread API to function, thread + support has to be enabled in the runtime system. An Erlang driver + can check if thread support is enabled by use of + driver_system_info(). + Note that some functions in the Erlang driver API are thread-safe + only when the runtime system has SMP support, also this + information can be retrieved via + driver_system_info(). + Also note that a lot of functions in the Erlang driver API are + not thread-safe regardless of whether SMP support is + enabled or not. If a function isn't documented as thread-safe it + is not thread-safe. +

+

NOTE: When executing in an emulator thread, it is + very important that you unlock all locks you + have locked before letting the thread out of your control; + otherwise, you are very likely to deadlock the whole + emulator. If you need to use thread specific data in an emulator + thread, only have the thread specific data set while the thread is + under your control, and clear the thread specific data before + you let the thread out of your control. +

+

In the future there will probably be debug functionality + integrated with the Erlang driver thread API. All functions + that create entities take a name argument. Currently + the name argument is unused, but it will be used when + the debug functionality has been implemented. If you name all + entities created well, the debug functionality will be able + to give you better error reports. +

+ + Adding / remove drivers + A driver can add and later remove drivers. + Monitoring processes + A driver can monitor a process that does not own a port. + Version management + + +

Version management is enabled for drivers that have set the + extended_marker + field of their + driver_entry + to ERL_DRV_EXTENDED_MARKER. erl_driver.h defines + ERL_DRV_EXTENDED_MARKER, + ERL_DRV_EXTENDED_MAJOR_VERSION, and + ERL_DRV_EXTENDED_MINOR_VERSION. + ERL_DRV_EXTENDED_MAJOR_VERSION will be incremented when + driver incompatible changes are made to the Erlang runtime + system. Normally it will suffice to recompile drivers when the + ERL_DRV_EXTENDED_MAJOR_VERSION has changed, but it + could, under rare circumstances, mean that drivers have to + be slightly modified. If so, this will of course be documented. + ERL_DRV_EXTENDED_MINOR_VERSION will be incremented when + new features are added. The runtime system use 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 + minor version used by the driver is greater than the one used + by the runtime system.

+

The emulator tries to check that a driver that doesn't use the + extended driver interface isn't incompatible when loading it. + 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 + interface, the emulator can verify that it isn't of an incompatible + driver version. You are therefore advised to use the extended driver + interface.

+ + +
+ +
+ DATA TYPES + + + ErlDrvSysInfo + +

+ +typedef struct ErlDrvSysInfo { + int driver_major_version; + int driver_minor_version; + char *erts_version; + char *otp_release; + int thread_support; + int smp_support; + int async_threads; + int scheduler_threads; +} ErlDrvSysInfo; + + +

+ The ErlDrvSysInfo structure is used for storage of + information about the Erlang runtime system. + driver_system_info() + will write the system information when passed a reference to + a ErlDrvSysInfo structure. A description of the + fields in the structure follow: +

+ + driver_major_version + The value of + ERL_DRV_EXTENDED_MAJOR_VERSION + when the runtime system was compiled. This value is the same + as the value of + ERL_DRV_EXTENDED_MAJOR_VERSION + used when compiling the driver; otherwise, the runtime system + would have refused to load the driver. + + driver_minor_version + The value of + ERL_DRV_EXTENDED_MINOR_VERSION + when the runtime system was compiled. This value might differ + from the value of + ERL_DRV_EXTENDED_MINOR_VERSION + used when compiling the driver. + + erts_version + A string containing the version number of the runtime system + (the same as returned by + erlang:system_info(version)). + + otp_release + A string containing the OTP release number + (the same as returned by + erlang:system_info(otp_release)). + + thread_support + A value != 0 if the runtime system has thread support; + otherwise, 0. + + smp_support + A value != 0 if the runtime system has SMP support; + otherwise, 0. + + thread_support + A value != 0 if the runtime system has thread support; + otherwise, 0. + + smp_support + A value != 0 if the runtime system has SMP support; + otherwise, 0. + + async_threads + The number of async threads in the async thread pool used + by driver_async() + (the same as returned by + erlang:system_info(thread_pool_size)). + + scheduler_threads + The number of scheduler threads used by the runtime system + (the same as returned by + erlang:system_info(schedulers)). + + + + + ErlDrvBinary + +

+ +typedef struct ErlDrvBinary { + int orig_size; + char orig_bytes[]; +} ErlDrvBinary; + +

The ErlDrvBinary structure is a binary, as sent + between the emulator and the driver. All binaries are + reference counted; when driver_binary_free is called, + the reference count is decremented, when it reaches zero, + the binary is deallocated. The orig_size is the size + of the binary, and orig_bytes is the buffer. The + ErlDrvBinary does not have a fixed size, its size is + orig_size + 2 * sizeof(int).

+ +

The refc field has been removed. The reference count of + an ErlDrvBinary is now stored elsewhere. The + reference count of an ErlDrvBinary can be accessed via + driver_binary_get_refc(), + driver_binary_inc_refc(), + and + driver_binary_dec_refc().

+ +

Some driver calls, such as driver_enq_binary, + increments the driver reference count, and others, such as + driver_deq decrements it.

+

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.

+

A driver binary allocated in the driver, with + driver_alloc_binary, should be freed in the driver (unless otherwise stated), + with driver_free_binary. (Note that this doesn't + necessarily deallocate it, if the driver is still referred + in the emulator, the ref-count will not go to zero.)

+

Driver binaries are used in the driver_output2 and + driver_outputv calls, and in the queue. Also the + driver call-back outputv uses driver + binaries.

+

If the driver of 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 stop call-back, with + driver_free_binary.

+

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.

+

From 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).

+ + ErlDrvData + +

The ErlDrvData is a handle to driver-specific data, + passed to the driver call-backs. It is a pointer, and is + most often casted to a specific pointer in the driver.

+ + SysIOVec + +

This is a system I/O vector, as used by writev on + unix and WSASend on Win32. It is used in + ErlIOVec.

+ + ErlIOVec + +

+ +typedef struct ErlIOVec { + int vsize; + int size; + SysIOVec* iov; + >ErlDrvBinary** binv; +} ErlIOVec; + +

The I/O vector used by the emulator and drivers, is a list + of binaries, with a SysIOVec pointing to the buffers + of the binaries. It is used in driver_outputv and the + outputv + driver call-back. Also, the driver queue is an + ErlIOVec.

+ + + ErlDrvMonitor + +

When a driver creates a monitor for a process, a + ErlDrvMonitor is filled in. This is an opaque + data-type which can be assigned to but not compared without + using the supplied compare function (i.e. it behaves like a struct).

+

The driver writer should provide the memory for storing the + monitor when calling driver_monitor_process. The + address of the data is not stored outside of the driver, so + the ErlDrvMonitor can be used as any other datum, it + can be copied, moved in memory, forgotten etc.

+ + ErlDrvNowData + +

The ErlDrvNowData structure holds a timestamp + consisting of three values measured from some arbitrary + point in the past. The three structure members are:

+ + megasecs + The number of whole megaseconds elapsed since the arbitrary + point in time + secs + The number of whole seconds elapsed since the arbitrary + point in time + microsecs + The number of whole microseconds elapsed since the arbitrary + point in time + + + ErlDrvPDL + +

If certain port specific data have to be accessed from other + threads than those calling the driver call-backs, a port data lock + can be used in order to synchronize the operations on the data. + Currently, the only port specific data that the emulator + associates with the port data lock is the driver queue.

+

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 + create the port data lock by calling + driver_pdl_create(). + NOTE: Once the port data lock has been created, every + access to data associated with the port data lock have to be done + while having the port data lock locked. The port data lock is + locked, and unlocked, respectively, by use of + driver_pdl_lock(), and + driver_pdl_unlock().

+

A port data lock is reference counted, and when the reference + count reach 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 + reference count when an async job is enqueued and decrement + it after an async job has been invoked, or canceled. Besides + this, it is the responsibility of the driver to ensure that + the reference count does not reach zero before the last use + of the lock by the driver has been made. The reference count + can be read, incremented, and decremented, respectively, by + use of + driver_pdl_get_refc(), + driver_pdl_inc_refc(), and + driver_pdl_dec_refc().

+ + + ErlDrvTid + +

Thread identifier.

+

See also: + erl_drv_thread_create(), + erl_drv_thread_exit(), + erl_drv_thread_join(), + erl_drv_thread_self(), + and + erl_drv_equal_tids(). +

+ + ErlDrvThreadOpts + +

+ + int suggested_stack_size; + +

Thread options structure passed to + erl_drv_thread_create(). + Currently the following fields exist: +

+ + suggested_stack_size + A suggestion, in kilo-words, on how large stack to use. A value less + than zero means default size. + + +

See also: + erl_drv_thread_opts_create(), + erl_drv_thread_opts_destroy(), + and + erl_drv_thread_create(). +

+ + + ErlDrvMutex + +

Mutual exclusion lock. Used for synchronizing access to shared data. + Only one thread at a time can lock a mutex. +

+

See also: + erl_drv_mutex_create(), + erl_drv_mutex_destroy(), + erl_drv_mutex_lock(), + erl_drv_mutex_trylock(), + and + erl_drv_mutex_unlock(). +

+ + ErlDrvCond + +

Condition variable. Used when threads need to wait for a specific + condition to appear before continuing execution. Condition variables + need to be used with associated mutexes. +

+

See also: + erl_drv_cond_create(), + erl_drv_cond_destroy(), + erl_drv_cond_signal(), + erl_drv_cond_broadcast(), + and + erl_drv_cond_wait(). +

+ + ErlDrvRWLock + +

Read/write lock. Used to allow multiple threads to read shared data + while only allowing one thread to write the same data. Multiple threads + can read lock an rwlock at the same time, while only one thread can + read/write lock an rwlock at a time. +

+

See also: + erl_drv_rwlock_create(), + erl_drv_rwlock_destroy(), + erl_drv_rwlock_rlock(), + erl_drv_rwlock_tryrlock(), + erl_drv_rwlock_runlock(), + erl_drv_rwlock_rwlock(), + erl_drv_rwlock_tryrwlock(), + and + erl_drv_rwlock_rwunlock(). +

+ + ErlDrvTSDKey + +

Key which thread specific data can be associated with.

+

See also: + erl_drv_tsd_key_create(), + erl_drv_tsd_key_destroy(), + erl_drv_tsd_set(), + and + erl_drv_tsd_get(). +

+ + +
+ + + + voiddriver_system_info(ErlDrvSysInfo *sys_info_ptr, size_t size) + Get information about the Erlang runtime system + + +

This function will write information about the Erlang runtime + system into the + ErlDrvSysInfo + structure referred to by the first argument. The second + argument should be the size of the + ErlDrvSysInfo + structure, i.e., sizeof(ErlDrvSysInfo).

+

See the documentation of the + ErlDrvSysInfo + structure for information about specific fields.

+ + + + intdriver_output(ErlDrvPort port, char *buf, int len) + Send data from driver to port owner + + +

The driver_output function is used to send data from + the driver up to the emulator. The data will be received as + terms or binary data, depending on how the driver port was + opened.

+

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.)

+

The parameter buf points to the data to send, and + len is the number of bytes.

+

The return value for all output functions is 0. (Unless the + driver is used for distribution, in which case it can fail + and return -1. For normal use, the output function always + returns 0.)

+ + + + intdriver_output2(ErlDrvPort port, char *hbuf, int hlen, char *buf, int len) + Send data and binary data to port owner + + +

The driver_output2 function first sends hbuf + (length in hlen) data as a list, regardless of port + settings. Then buf is sent as a binary or list. + E.g. if hlen is 3 then the port owner process will + receive [H1, H2, H3 | T].

+

The point of sending data as a list header, is to facilitate + matching on the data received.

+

The return value is 0 for normal use.

+ + + + intdriver_output_binary(ErlDrvPort port, char *hbuf, int hlen, ErlDrvBinary* bin, int offset, int len) + Send data from a driver binary to port owner + + +

This function sends data to port owner process from a + driver binary, it has a header buffer (hbuf + and hlen) just like driver_output2. The + hbuf parameter can be NULL.

+

The parameter offset is an offset into the binary and + len is the number of bytes to send.

+

Driver binaries are created with driver_alloc_binary.

+

The data in the header is sent as a list and the binary as + an Erlang binary in the tail of the list.

+

E.g. if hlen is 2, then the port owner process will + receive >]]]>.

+

The return value is 0 for normal use.

+

Note that, using the binary syntax in Erlang, the driver + application can match the header directly from the binary, + so the header can be put in the binary, and hlen can be set + to 0.

+ + + + intdriver_outputv(ErlDrvPort port, char* hbuf, int hlen, ErlIOVec *ev, int skip) + Send vectorized data to port owner + + +

This function sends data from an IO vector, ev, to + the port owner process. It has a header buffer (hbuf + and hlen), just like driver_output2.

+

The skip parameter is a number of bytes to skip of + the ev vector from the head.

+

You get vectors of ErlIOVec type from the driver + queue (see below), and the outputv driver entry + function. You can also make them yourself, if you want to + send several ErlDrvBinary buffers at once. Often + it is faster to use driver_output or + driver_output_binary.

+

E.g. if hlen is 2 and ev points to an array of + three binaries, the port owner process will receive >, <> | <>]]]>.

+

The return value is 0 for normal use.

+

The comment for driver_output_binary applies for + driver_outputv too.

+ + + + intdriver_vec_to_buf(ErlIOVec *ev, char *buf, int len) + Collect data segments into a buffer + + +

This function collects several segments of data, referenced + by ev, by copying them in order to the buffer + buf, of the size len.

+

If the data is to be sent from the driver to the port owner + process, it is faster to use driver_outputv.

+

The return value is the space left in the buffer, i.e. if + the ev contains less than len bytes it's the + difference, and if ev contains len bytes or + more, it's 0. This is faster if there is more than one header byte, + since the binary syntax can construct integers directly from + the binary.

+ + + + intdriver_set_timer(ErlDrvPort port, unsigned long time) + Set a timer to call the driver + + +

This function sets a timer on the driver, which will count + down and call the driver when it is timed out. The + time parameter is the time in milliseconds before the + timer expires.

+

When the timer reaches 0 and expires, the driver entry + function timeout is called.

+

Note that there is only one timer on each driver instance; + setting a new timer will replace an older one.

+

Return value i 0 (-1 only when the timeout driver + function is NULL).

+ + + + intdriver_cancel_timer(ErlDrvPort port) + Cancel a previously set timer + + +

This function cancels a timer set with + driver_set_timer.

+

The return value is 0.

+ + + + intdriver_read_timer(ErlDrvPort port, unsigned long *time_left) + Read the time left before timeout + + +

This function reads the current time of a timer, and places + the result in time_left. This is the time in + milliseconds, before the timeout will occur.

+

The return value is 0.

+ + + + intdriver_get_now(ErlDrvNowData *now) + Read a system timestamp + + +

This function reads a timestamp into the memory pointed to by + the parameter now. See the description of ErlDrvNowData for + specification of it's fields.

+

The return value is 0 unless the now pointer is not + valid, in which case it is < 0.

+ + + + intdriver_select(ErlDrvPort port, ErlDrvEvent event, int mode, int on) + Provide an event for having the emulator call the driver + + +

This function is used by drivers to provide the emulator with + events to check for. This enables the emulator to call the driver + when something has happened asynchronously.

+

The event argument identifies an OS-specific event object. + On Unix systems, the functions select/poll are used. The + event object must be a socket or pipe (or other object that + select/poll can use). + On windows, the Win32 API function WaitForMultipleObjects + is used. This places other restriction on the event object. + Refer to the Win32 SDK documentation.

+

The on parameter should be 1 for setting events + and 0 for clearing them.

+

The mode argument is bitwise-or combination of + ERL_DRV_READ, ERL_DRV_WRITE and ERL_DRV_USE. + The first two specifies whether to wait for read events and/or write + events. A fired read event will call + ready_input + while a fired write event will call + ready_output. +

+ +

Some OS (Windows) does not differ between read and write events. + The call-back for a fired event then only depends on the value of mode.

+ +

ERL_DRV_USE specifies if we are using the event object or if we want to close it. + On an emulator with SMP support, it is not safe to clear all events + and then close the event object after driver_select has + returned. Another thread may still be using the event object + internally. To safely close an event object call + driver_select with ERL_DRV_USE and on==0. That + will clear all events and then call + stop_select + when it is safe to close the event object. + ERL_DRV_USE should be set together with the first event + for an event object. It is harmless to set ERL_DRV_USE + even though it already has been done. Clearing all events but keeping + ERL_DRV_USE set will indicate that we are using the event + object and probably will set events for it again.

+ +

ERL_DRV_USE was added in OTP release R13. Old drivers will still work + as before. But it is recommended to update them to use ERL_DRV_USE and + stop_select to make sure that event objects are closed in a safe way.

+ +

The return value is 0 (Failure, -1, only if the + ready_input/ready_output is + NULL.

+ + + + void *driver_alloc(size_t size) + Allocate memory + + +

This function allocates a memory block of the size specified + in size, and returns it. This only fails on out of + memory, in that case NULL is returned. (This is most + often a wrapper for malloc).

+

Memory allocated must be explicitly freed with a corresponding + call to driver_free (unless otherwise stated).

+

This function is thread-safe.

+ + + + void *driver_realloc(void *ptr, size_t size) + Resize an allocated memory block + + +

This function resizes a memory block, either in place, or by + allocating a new block, copying the data and freeing the old + block. A pointer is returned to the reallocated memory. On + failure (out of memory), NULL is returned. (This is + most often a wrapper for realloc.)

+

This function is thread-safe.

+ + + + voiddriver_free(void *ptr) + Free an allocated memory block + + +

This function frees the memory pointed to by ptr. The + memory should have been allocated with + driver_alloc. All allocated memory should be + deallocated, just once. There is no garbage collection in + drivers.

+

This function is thread-safe.

+ + + + ErlDrvBinary*driver_alloc_binary(int size) + Allocate a driver binary + + +

This function allocates a driver binary with a memory block + of at least size bytes, and returns a pointer to it, + or NULL on failure (out of memory). When a driver binary has + been sent to the emulator, it must not be altered. Every + allocated binary should be freed by a corresponding call to + driver_free_binary (unless otherwise stated).

+

Note that a driver binary has an internal reference counter, + this means that calling driver_free_binary it may not + actually dispose of it. If it's sent to the emulator, it may + be referenced there.

+

The driver binary has a field, orig_bytes, which + marks the start of the data in the binary.

+

This function is thread-safe.

+ + + + ErlDrvBinary*driver_realloc_binary(ErlDrvBinary *bin, int size) + Resize a driver binary + + +

This function resizes a driver binary, while keeping the + data. The resized driver binary is returned. On failure (out + of memory), NULL is returned.

+

This function is only thread-safe when the emulator with SMP + support is used.

+ + + + voiddriver_free_binary(ErlDrvBinary *bin) + Free a driver binary + + +

This function frees a driver binary bin, allocated + previously with driver_alloc_binary. Since binaries + in Erlang are reference counted, the binary may still be + around.

+

This function is only thread-safe when the emulator with SMP + support is used.

+ + + + longdriver_binary_get_refc(ErlDrvBinary *bin) + Get the reference count of a driver binary + + +

Returns current reference count on bin.

+

This function is only thread-safe when the emulator with SMP + support is used.

+ + + + longdriver_binary_inc_refc(ErlDrvBinary *bin) + Increment the reference count of a driver binary + + +

Increments the reference count on bin and returns + the reference count reached after the increment.

+

This function is only thread-safe when the emulator with SMP + support is used.

+ + + + longdriver_binary_dec_refc(ErlDrvBinary *bin) + Decrement the reference count of a driver binary + + +

Decrements the reference count on bin and returns + the reference count reached after the decrement.

+

This function is only thread-safe when the emulator with SMP + support is used.

+ +

You should normally decrement the reference count of a + driver binary by calling + driver_free_binary(). + driver_binary_dec_refc() does not free + the binary if the reference count reaches zero. Only + use driver_binary_dec_refc() when you are sure + not to reach a reference count of zero.

+ + + + + intdriver_enq(ErlDrvPort port, char* buf, int len) + Enqueue data in the driver queue + + +

This function enqueues data in the driver queue. The data in + buf is copied (len bytes) and placed at the + end of the driver queue. The driver queue is normally used + in a FIFO way.

+

The driver queue is available to queue output from the + emulator to the driver (data from the driver to the emulator + is queued by the emulator in normal erlang message + queues). This can be useful if the driver has to wait for + slow devices etc, and wants to yield back to the + emulator. The driver queue is implemented as an ErlIOVec.

+

When the queue contains data, the driver won't close, until + the queue is empty.

+

The return value is 0.

+

This function can be called from an arbitrary thread if a + port data lock + associated with the port is locked by the calling + thread during the call.

+ + + + intdriver_pushq(ErlDrvPort port, char* buf, int len) + Push data at the head of the driver queue + + +

This function puts data at the head of the driver queue. The + data in buf is copied (len bytes) and placed + at the beginning of the queue.

+

The return value is 0.

+

This function can be called from an arbitrary thread if a + port data lock + associated with the port is locked by the calling + thread during the call.

+ + + + intdriver_deq(ErlDrvPort port, int size) + Dequeue data from the head of the driver queue + + +

This function dequeues data by moving the head pointer + forward in the driver queue by size bytes. The data + in the queue will be deallocated.

+

The return value is the number of bytes remaining in the queue + or -1 on failure.

+

This function can be called from an arbitrary thread if a + port data lock + associated with the port is locked by the calling + thread during the call.

+ + + + intdriver_sizeq(ErlDrvPort port) + Return the size of the driver queue + + +

This function returns the number of bytes currently in the + driver queue.

+

This function can be called from an arbitrary thread if a + port data lock + associated with the port is locked by the calling + thread during the call.

+ + + + intdriver_enq_bin(ErlDrvPort port, ErlDrvBinary *bin, int offset, int len) + Enqueue binary in the driver queue + + +

This function enqueues a driver binary in the driver + queue. The data in bin at offset with length + len is placed at the end of the queue. This function + is most often faster than driver_enq, because the + data doesn't have to be copied.

+

This function can be called from an arbitrary thread if a + port data lock + associated with the port is locked by the calling + thread during the call.

+

The return value is 0.

+ + + + intdriver_pushq_bin(ErlDrvPort port, ErlDrvBinary *bin, int offset, int len) + Push binary at the head of the driver queue + + +

This function puts data in the binary bin, at + offset with length len at the head of the + driver queue. It is most often faster than + driver_pushq, because the data doesn't have to be + copied.

+

This function can be called from an arbitrary thread if a + port data lock + associated with the port is locked by the calling + thread during the call.

+

The return value is 0.

+ + + + SysIOVec*driver_peekq(ErlDrvPort port, int *vlen) + Get the driver queue as a vector + + +

This function retrieves the driver queue as a pointer to an + array of SysIOVecs. It also returns the number of + elements in vlen. This is the only way to get data + out of the queue.

+

Nothing is remove from the queue by this function, that must be done + with driver_deq.

+

The returned array is suitable to use with the Unix system + call writev.

+

This function can be called from an arbitrary thread if a + port data lock + associated with the port is locked by the calling + thread during the call.

+ + + + intdriver_enqv(ErlDrvPort port, ErlIOVec *ev, int skip) + Enqueue vector in the driver queue + + +

This function enqueues the data in ev, skipping the + first skip bytes of it, at the end of the driver + queue. It is faster than driver_enq, because the data + doesn't have to be copied.

+

The return value is 0.

+

This function can be called from an arbitrary thread if a + port data lock + associated with the port is locked by the calling + thread during the call.

+ + + + intdriver_pushqv(ErlDrvPort port, ErlIOVec *ev, int skip) + Push vector at the head of the driver queue + + +

This function puts the data in ev, skipping the first + skip bytes of it, at the head of the driver queue. + It is faster than driver_pushq, because the data + doesn't have to be copied.

+

The return value is 0.

+

This function can be called from an arbitrary thread if a + port data lock + associated with the port is locked by the calling + thread during the call.

+ + + + ErlDrvPDLdriver_pdl_create(ErlDrvPort port) + Create a port data lock + + +

This function creates a port data lock associated with + the port. NOTE: Once a port data lock has + been created, it has to be locked during all operations + on the driver queue of the port.

+

On success a newly created port data lock is returned. On + failure NULL is returned. driver_pdl_create() will + fail if port is invalid or if a port data lock already has + been associated with the port.

+ + + + voiddriver_pdl_lock(ErlDrvPDL pdl) + Lock port data lock + + +

This function locks the port data lock passed as argument + (pdl).

+

This function is thread-safe.

+ + + + voiddriver_pdl_unlock(ErlDrvPDL pdl) + Unlock port data lock + + +

This function unlocks the port data lock passed as argument + (pdl).

+

This function is thread-safe.

+ + + + longdriver_pdl_get_refc(ErlDrvPDL pdl) + + + +

This function returns the current reference count of + the port data lock passed as argument (pdl).

+

This function is thread-safe.

+ + + + longdriver_pdl_inc_refc(ErlDrvPDL pdl) + + + +

This function increments the reference count of + the port data lock passed as argument (pdl).

+

The current reference count after the increment has + been performed is returned.

+

This function is thread-safe.

+ + + + longdriver_pdl_dec_refc(ErlDrvPDL pdl) + + + +

This function decrements the reference count of + the port data lock passed as argument (pdl).

+

The current reference count after the decrement has + been performed is returned.

+

This function is thread-safe.

+ + + + intdriver_monitor_process(ErlDrvPort port, ErlDrvTermData process, ErlDrvMonitor *monitor) + Monitor a process from a driver + + +

Start monitoring a process from a driver. When a process is + monitored, a process exit will result in a call to the + provided process_exit call-back + in the ErlDrvEntry + structure. The ErlDrvMonitor structure is filled in, for later + removal or compare.

+

The process parameter should be the return value of an + earlier call to driver_caller or driver_connected call.

+

The function returns 0 on success, < 0 if no call-back is + provided and > 0 if the process is no longer alive.

+ + + + intdriver_demonitor_process(ErlDrvPort port, const ErlDrvMonitor *monitor) + Stop monitoring a process from a driver + + +

This function cancels an monitor created earlier.

+

The function returns 0 if a monitor was removed and > 0 + if the monitor did no longer exist.

+ + + + ErlDrvTermDatadriver_get_monitored_process(ErlDrvPort port, const ErlDrvMonitor *monitor) + Retrieve the process id from a monitor + + +

The function returns the process id associated with a living + monitor. It can be used in the process_exit call-back to + get the process identification for the exiting process.

+

The function returns driver_term_nil if the monitor + no longer exists.

+ + + + intdriver_compare_monitors(const ErlDrvMonitor *monitor1, const ErlDrvMonitor *monitor2) + Compare two monitors + + +

This function is used to compare two ErlDrvMonitors. It + can also be used to imply some artificial order on monitors, + for whatever reason.

+

The function returns 0 if monitor1 and + monitor2 are equal, < 0 if monitor1 is less + than monitor2 and > 0 if monitor1 is greater + than monitor2.

+ + + + voidadd_driver_entry(ErlDrvEntry *de) + Add a driver entry + + +

This function adds a driver entry to the list of drivers + known by Erlang. The init function of the de + parameter is called.

+ +

To use this function for adding drivers residing in + dynamically loaded code is dangerous. If the driver code + for the added driver resides in the same dynamically + loaded module (i.e. .so file) as a normal + dynamically loaded driver (loaded with the erl_ddll + interface), the caller should call driver_lock_driver before + adding driver entries.

+

Use of this function is generally deprecated.

+ + + + + intremove_driver_entry(ErlDrvEntry *de) + Remove a driver entry + + +

This function removes a driver entry de previously + added with add_driver_entry.

+

Driver entries added by the erl_ddll erlang interface can + not be removed by using this interface.

+ + + + char*erl_errno_id(int error) + Get erlang error atom name from error number + + +

This function returns the atom name of the erlang error, + given the error number in error. Error atoms are: + einval, enoent, etc. It can be used to make + error terms from the driver.

+ + + + voidset_busy_port(ErlDrvPort port, int on) + Signal or unsignal port as busy + + +

This function set and resets the busy status of the port. If + on is 1, the port is set to busy, if it's 0 the port + is set to not busy.

+

When the port is busy, sending to it with Port ! Data + or port_command/2, will block the port owner process, + until the port is signaled as not busy.

+

If the + + has been set in the + driver_entry, + data can be forced into the driver via + port_command(Port, Data, [force]) + even though the driver has signaled that it is busy. +

+ + + + voidset_port_control_flags(ErlDrvPort port, int flags) + Set flags on how to handle control entry function + + +

This function sets flags for how the control driver entry + function will return data to the port owner process. (The + control function is called from port_control/3 + in erlang.)

+

Currently there are only two meaningful values for + flags: 0 means that data is returned in a list, and + PORT_CONTROL_FLAG_BINARY means data is returned as + a binary from control.

+ + + + intdriver_failure_eof(ErlDrvPort port) + Fail with EOF + + +

This function signals to erlang that the driver has + encountered an EOF and should be closed, unless the port was + opened with the eof option, in that case eof is sent + to the port. Otherwise, the port is close and an + 'EXIT' message is sent to the port owner process.

+

The return value is 0.

+ + + + intdriver_failure_atom(ErlDrvPort port, char *string) + intdriver_failure_posix(ErlDrvPort port, int error) + intdriver_failure(ErlDrvPort port, int error) + Fail with error + + + + +

These functions signal to Erlang that the driver has + encountered an error and should be closed. The port is + closed and the tuple {'EXIT', error, Err}, is sent to + the port owner process, where error is an error atom + (driver_failure_atom and + driver_failure_posix), or an integer + (driver_failure).

+

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 + driver_output.

+

The return value is 0.

+ + + + ErlDrvTermDatadriver_connected(ErlDrvPort port) + Return the port owner process + + +

This function returns the port owner process.

+ + + + ErlDrvTermDatadriver_caller(ErlDrvPort port) + Return the process making the driver call + + +

This function returns the process id of the process that + made the current call to the driver. The process id can be + used with driver_send_term to send back data to the + caller. driver_caller() only return valid data + when currently executing in one of the following driver + callbacks:

+ + start + Called from open_port/2. + output + Called from erlang:send/2, and + erlang:port_command/2 + outputv + Called from erlang:send/2, and + erlang:port_command/2 + control + Called from erlang:port_control/3 + call + Called from erlang:port_call/3 + + + + + intdriver_output_term(ErlDrvPort port, ErlDrvTermData* term, int n) + Send term data from driver to port owner + + +

This functions sends data in the special driver term + format. This is a fast way to deliver term data from a + driver. It also needs no binary conversion, so the port + owner process receives data as normal Erlang terms.

+

The term parameter points to an array of + ErlDrvTermData, with n elements. This array + contains terms described in the driver term format. Every + term consists of one to four elements in the array. The + term first has a term type, and then arguments.

+

Tuple and lists (with the exception of strings, see below), + are built in reverse polish notation, so that to build a + tuple, the elements are given first, and then the tuple + term, with a count. Likewise for lists.

+

A tuple must be specified with the number of elements. (The + elements precedes the ERL_DRV_TUPLE term.)

+

A list must be specified with the number of elements, + including the tail, which is the last term preceding + ERL_DRV_LIST.

+

The special term ERL_DRV_STRING_CONS is used to + "splice" in a string in a list, a string given this way is + not a list per se, but the elements are elements of the + surrounding list.

+ 
+Term type            Argument(s)
+===========================================
+ERL_DRV_NIL          
+ERL_DRV_ATOM         ErlDrvTermData atom (from driver_mk_atom(char *string))
+ERL_DRV_INT          ErlDrvSInt integer
+ERL_DRV_UINT         ErlDrvUInt integer
+ERL_DRV_INT64        ErlDrvSInt64 *integer_ptr
+ERL_DRV_UINT64       ErlDrvUInt64 *integer_ptr
+ERL_DRV_PORT         ErlDrvTermData port (from driver_mk_port(ErlDrvPort port))
+ERL_DRV_BINARY       ErlDrvBinary *bin, ErlDrvUInt len, ErlDrvUInt offset
+ERL_DRV_BUF2BINARY   char *buf, ErlDrvUInt len
+ERL_DRV_STRING       char *str, int len
+ERL_DRV_TUPLE        int sz
+ERL_DRV_LIST         int sz
+ERL_DRV_PID          ErlDrvTermData pid (from driver_connected(ErlDrvPort port) or driver_caller(ErlDrvPort port))
+ERL_DRV_STRING_CONS  char *str, int len
+ERL_DRV_FLOAT        double *dbl
+ERL_DRV_EXT2TERM     char *buf, ErlDrvUInt len
+
+

The unsigned integer data type ErlDrvUInt and the + signed integer data type ErlDrvSInt are 64 bits wide + on a 64 bit runtime system and 32 bits wide on a 32 bit + runtime system. They were introduced in erts version 5.6, + and replaced some of the int arguments in the list above. +

+

The unsigned integer data type ErlDrvUInt64 and the + signed integer data type ErlDrvSInt64 are always 64 bits + wide. They were introduced in erts version 5.7.4. +

+ +

To build the tuple {tcp, Port, [100 | Binary]}, the + following call could be made.

+ + +

Where bin is a driver binary of length at least 50 + and port is a port handle. Note that the ERL_DRV_LIST + comes after the elements of the list, likewise the + ERL_DRV_TUPLE.

+

The term ERL_DRV_STRING_CONS is a way to construct + strings. It works differently from how ERL_DRV_STRING + works. ERL_DRV_STRING_CONS builds a string list in + reverse order, (as opposed to how ERL_DRV_LIST + works), concatenating the strings added to a list. The tail + must be given before ERL_DRV_STRING_CONS.

+

The ERL_DRV_STRING constructs a string, and ends + it. (So it's the same as ERL_DRV_NIL followed by + ERL_DRV_STRING_CONS.)

+ +

+ +

The ERL_DRV_EXT2TERM term type is used for passing a + term encoded with the + external format, + i.e., a term that has been encoded by + erlang:term_to_binary, + erl_interface, etc. + For example, if binp is a pointer to an ErlDrvBinary + that contains the term {17, 4711} encoded with the + external format + and you want to wrap it in a two tuple with the tag my_tag, + i.e., {my_tag, {17, 4711}}, you can do as follows: +

+ orig_bytes, binp->orig_size + ERL_DRV_TUPLE, 2, + }; + driver_output_term(port, spec, sizeof(spec) / sizeof(spec[0])); + ]]> +

If you want to pass a binary and doesn't already have the content + of the binary in an ErlDrvBinary, you can benefit from using + ERL_DRV_BUF2BINARY instead of creating an ErlDrvBinary + via driver_alloc_binary() and then pass the binary via + ERL_DRV_BINARY. The runtime system will often allocate + binaries smarter if ERL_DRV_BUF2BINARY is used. + However, if the content of the binary to pass already resides in + an ErlDrvBinary, it is normally better to pass the binary + using ERL_DRV_BINARY and the ErlDrvBinary in question. +

+

The ERL_DRV_UINT, ERL_DRV_BUF2BINARY, and + ERL_DRV_EXT2TERM term types were introduced in the 5.6 + version of erts. +

+

Note that this function is not thread-safe, not + even when the emulator with SMP support is used.

+ + + + ErlDrvTermDatadriver_mk_atom(char* string) + Make an atom from a name + + +

This function returns an atom given a name + string. The atom is created and won't change, so the + return value may be saved and reused, which is faster than + looking up the atom several times.

+ + + + ErlDrvTermDatadriver_mk_port(ErlDrvPort port) + Make a erlang term port from a port + + +

This function converts a port handle to the erlang term + format, usable in the driver_output_send function.

+ + + + intdriver_send_term(ErlDrvPort port, ErlDrvTermData receiver, ErlDrvTermData* term, int n) + Send term data to other process than port owner process + + +

This function is the only way for a driver to send data to + other processes than the port owner process. The + receiver parameter specifies the process to receive + the data.

+

The parameters term and n does the same thing + as in driver_output_term.

+

This function is only thread-safe when the emulator with SMP + support is used.

+ + + + longdriver_async (ErlDrvPort port, unsigned int* key, void (*async_invoke)(void*), void* async_data, void (*async_free)(void*)) + Perform an asynchronous call within a driver + + +

This function performs an asynchronous call. The function + async_invoke is invoked in a thread separate from the + emulator thread. This enables the driver to perform + time-consuming, blocking operations without blocking the + emulator.

+

Erlang is by default started without an async thread pool. The + number of async threads that the runtime system should use + is specified by the + +A + command line argument of erl(1). + If no async thread pool is available, the call is made + synchronously in the thread calling driver_async(). The + current number of async threads in the async thread pool can be + retrieved via + driver_system_info().

+

If there is a thread pool available, a thread will be + used. If the key argument is null, the threads from the + pool are used in a round-robin way, each call to + driver_async uses the next thread in the pool. With the + key argument set, this behaviour is changed. The two + same values of *key always get the same thread.

+

To make sure that a driver instance always uses the same + thread, the following call can be used:

+

+ +

It is enough to initialize myKey once for each + driver instance.

+

If a thread is already working, the calls will be + queued up and executed in order. Using the same thread for + each driver instance ensures that the calls will be made in + sequence.

+

The async_data is the argument to the functions + async_invoke and async_free. It's typically a + pointer to a structure that contains a pipe or event that + can be used to signal that the async operation completed. + The data should be freed in async_free, because it's + called if driver_async_cancel is called.

+

When the async operation is done, ready_async driver + entry function is called. If async_ready is null in + the driver entry, the async_free function is called + instead.

+

The return value is a handle to the asynchronous task, which + can be used as argument to driver_async_cancel.

+ +

As of erts version 5.5.4.3 the default stack size for + threads in the async-thread pool is 16 kilowords, + i.e., 64 kilobyte on 32-bit architectures. + This small default size has been chosen since the + amount of async-threads might be quite large. The + default stack size is enough for drivers delivered + with Erlang/OTP, but might not be sufficiently large + for other dynamically linked in drivers that use the + driver_async() functionality. A suggested stack size + for threads in the async-thread pool can be configured + via the + +a + command line argument of + erl(1).

+ + + + + intdriver_async_cancel(long id) + Cancel an asynchronous call + + +

This function cancels an asynchronous operation, by removing + it from the queue. Only functions in the queue can be + cancelled; if a function is executing, it's too late to + cancel it. The async_free function is also called.

+

The return value is 1 if the operation was removed from the + queue, otherwise 0.

+ + + + intdriver_lock_driver(ErlDrvPort port) + Make sure the driver is never unloaded + + +

This function locks the driver used by the port port + 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.

+ + + + ErlDrvPortdriver_create_port(ErlDrvPort port, ErlDrvTermData owner_pid, char* name, ErlDrvData drv_data) + Create a new port (driver instance) + +

This function creates a new port executing the same driver + code as the port creating the new port. + A short description of the arguments:

+ + port + The port handle of the port (driver instance) creating + the new port. + owner_pid + The process id of the Erlang process which will be + owner of the new port. This process will be linked + to the new port. You usually want to use + driver_caller(port) as owner_pid. + name + The port name of the new port. You usually want to + use the same port name as the driver name + (driver_name + field of the + driver_entry). + drv_data + The driver defined handle that will be passed in subsequent + calls to driver call-backs. Note, that the + driver start call-back + will not be called for this new driver instance. + The driver defined handle is normally created in the + driver start call-back + when a port is created via + erlang:open_port/2. + +

The caller of driver_create_port() is allowed to + manipulate the newly created port when driver_create_port() + has returned. When + port level locking + is used, the creating port is, however, only allowed to + manipulate the newly created port until the current driver + call-back that was called by the emulator returns.

+ +

When + port level locking + is used, the creating port is only allowed to manipulate + the newly created port until the current driver call-back + returns.

+ + + + + + interl_drv_thread_create(char *name, + ErlDrvTid *tid, + void * (*func)(void *), + void *arg, + ErlDrvThreadOpts *opts) + Create a thread + + +

Arguments:

+ + name + A string identifying the created thread. It will be used + to identify the thread in planned future debug + functionality. + + tid + A pointer to a thread identifier variable. + func + A pointer to a function to execute in the created thread. + arg + A pointer to argument to the func function. + opts + A pointer to thread options to use or NULL. + +

This function creates a new thread. On success 0 is returned; + otherwise, an errno value is returned to indicate the error. + The newly created thread will begin executing in the function pointed + to by func, and func will be passed arg as + argument. When erl_drv_thread_create() returns the thread + identifier of the newly created thread will be available in + *tid. opts can be either a NULL pointer, or a + pointer to an + ErlDrvThreadOpts + structure. If opts is a NULL pointer, default options + will be used; otherwise, the passed options will be used. +

+

You are not allowed to allocate the + ErlDrvThreadOpts + structure by yourself. It has to be allocated and + initialized by + erl_drv_thread_opts_create(). +

+

The created thread will terminate either when func returns + or if + erl_drv_thread_exit() + is called by the thread. The exit value of the thread is either + returned from func or passed as argument to + erl_drv_thread_exit(). + The driver creating the thread has the responsibility of joining the + thread, via + erl_drv_thread_join(), + before the driver is unloaded. It is not possible to create + "detached" threads, i.e., threads that don't need to be joined. +

+

All created threads need to be joined by the driver before + it is unloaded. If the driver fails to join all threads + created before it is unloaded, the runtime system will + most likely crash when the code of the driver is unloaded. +

+

This function is thread-safe.

+ + + + + ErlDrvThreadOpts *erl_drv_thread_opts_create(char *name) + Create thread options + + +

Arguments:

+ + name + A string identifying the created thread options. It will be used + to identify the thread options in planned future debug + functionality. + + +

This function allocates and initialize a thread option + structure. On failure NULL is returned. A thread option + structure is used for passing options to + erl_drv_thread_create(). + If the structure isn't modified before it is passed to + erl_drv_thread_create(), + the default values will be used. +

+

You are not allowed to allocate the + ErlDrvThreadOpts + structure by yourself. It has to be allocated and + initialized by erl_drv_thread_opts_create(). +

+

This function is thread-safe.

+ + + + + voiderl_drv_thread_opts_destroy(ErlDrvThreadOpts *opts) + Destroy thread options + + +

Arguments:

+ + opts + A pointer to thread options to destroy. + +

This function destroys thread options previously created by + erl_drv_thread_opts_create(). +

+

This function is thread-safe.

+ + + + + voiderl_drv_thread_exit(void *exit_value) + Terminate calling thread + + +

Arguments:

+ + exit_value + A pointer to an exit value or NULL. + +

This function terminates the calling thread with the exit + value passed as argument. You are only allowed to terminate + threads created with + erl_drv_thread_create(). + The exit value can later be retrieved by another thread via + erl_drv_thread_join(). +

+

This function is thread-safe.

+ + + + + interl_drv_thread_join(ErlDrvTid tid, void **exit_value) + Join with another thread + + +

Arguments:

+ + tid + The thread identifier of the thread to join. + exit_value + A pointer to a pointer to an exit value, or NULL. + +

This function joins the calling thread with another thread, i.e., + the calling thread is blocked until the thread identified by + tid has terminated. On success 0 is returned; + otherwise, an errno value is returned to indicate the error. + A thread can only be joined once. The behavior of joining + more than once is undefined, an emulator crash is likely. If + exit_value == NULL, the exit value of the terminated thread + will be ignored; otherwise, the exit value of the terminated thread + will be stored at *exit_value. +

+

This function is thread-safe.

+ + + + + ErlDrvTiderl_drv_thread_self(void) + Get the thread identifier of the current thread + + +

This function returns the thread identifier of the + calling thread. +

+

This function is thread-safe.

+ + + + + interl_drv_equal_tids(ErlDrvTid tid1, ErlDrvTid tid2) + Compare thread identifiers for equality + + +

Arguments:

+ + tid1 + A thread identifier. + tid2 + A thread identifier. + +

This function compares two thread identifiers for equality, + and returns 0 it they aren't equal, and + a value not equal to 0 if they are equal.

+

A Thread identifier may be reused very quickly after + a thread has terminated. Therefore, if a thread + corresponding to one of the involved thread identifiers + has terminated since the thread identifier was saved, + the result of erl_drv_equal_tids() might not give + expected result. +

+

This function is thread-safe.

+ + + + + ErlDrvMutex *erl_drv_mutex_create(char *name) + Create a mutex + + +

Arguments:

+ + name + A string identifying the created mutex. It will be used + to identify the mutex in planned future debug functionality. + + +

This function creates a mutex and returns a pointer to it. On + failure NULL is returned. The driver creating the mutex + has the responsibility of destroying it before the driver is + unloaded. +

+

This function is thread-safe.

+ + + + + voiderl_drv_mutex_destroy(ErlDrvMutex *mtx) + Destroy a mutex + + +

Arguments:

+ + mtx + A pointer to a mutex to destroy. + +

This function destroys a mutex previously created by + erl_drv_mutex_create(). + The mutex has to be in an unlocked state before being + destroyed. +

+

This function is thread-safe.

+ + + + + voiderl_drv_mutex_lock(ErlDrvMutex *mtx) + Lock a mutex + + +

Arguments:

+ + mtx + A pointer to a mutex to lock. + +

This function locks a mutex. The calling thread will be + blocked until the mutex has been locked. A thread + which currently has locked the mutex may not lock + the same mutex again. +

+

If you leave a mutex locked in an emulator thread + when you let the thread out of your control, you will + very likely deadlock the whole emulator. +

+

This function is thread-safe.

+ + + + + interl_drv_mutex_trylock(ErlDrvMutex *mtx) + Try lock a mutex + + +

Arguments:

+ + mtx + A pointer to a mutex to try to lock. + +

This function tries to lock a mutex. If successful 0, + is returned; otherwise, EBUSY is returned. A thread + which currently has locked the mutex may not try to + lock the same mutex again. +

+

If you leave a mutex locked in an emulator thread + when you let the thread out of your control, you will + very likely deadlock the whole emulator. +

+

This function is thread-safe.

+ + + + + voiderl_drv_mutex_unlock(ErlDrvMutex *mtx) + Unlock a mutex + + +

Arguments:

+ + mtx + A pointer to a mutex to unlock. + +

This function unlocks a mutex. The mutex currently has to be + locked by the calling thread. +

+

This function is thread-safe.

+ + + + + ErlDrvCond *erl_drv_cond_create(char *name) + Create a condition variable + + +

Arguments:

+ + name + A string identifying the created condition variable. It + will be used to identify the condition variable in planned + future debug functionality. + + +

This function creates a condition variable and returns a + pointer to it. On failure NULL is returned. The driver + creating the condition variable has the responsibility of + destroying it before the driver is unloaded.

+

This function is thread-safe.

+ + + + + voiderl_drv_cond_destroy(ErlDrvCond *cnd) + Destroy a condition variable + + +

Arguments:

+ + cnd + A pointer to a condition variable to destroy. + +

This function destroys a condition variable previously + created by + erl_drv_cond_create(). +

+

This function is thread-safe.

+ + + + + voiderl_drv_cond_signal(ErlDrvCond *cnd) + Signal on a condition variable + + +

Arguments:

+ + cnd + A pointer to a condition variable to signal on. + +

This function signals on a condition variable. That is, if + other threads are waiting on the condition variable being + signaled, one of them will be woken. +

+

This function is thread-safe.

+ + + + + voiderl_drv_cond_broadcast(ErlDrvCond *cnd) + Broadcast on a condition variable + + +

Arguments:

+ + cnd + A pointer to a condition variable to broadcast on. + +

This function broadcasts on a condition variable. That is, if + other threads are waiting on the condition variable being + broadcasted on, all of them will be woken. +

+

This function is thread-safe.

+ + + + + voiderl_drv_cond_wait(ErlDrvCond *cnd, ErlDrvMutex *mtx) + Wait on a condition variable + + +

Arguments:

+ + cnd + A pointer to a condition variable to wait on. + mtx + A pointer to a mutex to unlock while waiting. + + + +

This function waits on a condition variable. The calling + thread is blocked until another thread wakes it by signaling + or broadcasting on the condition variable. Before the calling + thread is blocked it unlocks the mutex passed as argument, and + when the calling thread is woken it locks the same mutex before + returning. That is, the mutex currently has to be locked by + the calling thread when calling this function. +

+

erl_drv_cond_wait() might return even though + no-one has signaled or broadcasted on the condition + variable. Code calling erl_drv_cond_wait() should + always be prepared for erl_drv_cond_wait() + returning even though the condition that the thread was + waiting for hasn't occurred. That is, when returning from + erl_drv_cond_wait() always check if the condition + has occurred, and if not call erl_drv_cond_wait() + again. +

+

This function is thread-safe.

+ + + + + ErlDrvRWLock *erl_drv_rwlock_create(char *name) + Create an rwlock + + +

Arguments:

+ + name + A string identifying the created rwlock. It will be used to + identify the rwlock in planned future debug functionality. + + +

This function creates an rwlock and returns a pointer to it. On + failure NULL is returned. The driver creating the rwlock + has the responsibility of destroying it before the driver is + unloaded. +

+

This function is thread-safe.

+ + + + + voiderl_drv_rwlock_destroy(ErlDrvRWLock *rwlck) + Destroy an rwlock + + +

Arguments:

+ + rwlck + A pointer to an rwlock to destroy. + +

This function destroys an rwlock previously created by + erl_drv_rwlock_create(). + The rwlock has to be in an unlocked state before being destroyed. +

+

This function is thread-safe.

+ + + + + voiderl_drv_rwlock_rlock(ErlDrvRWLock *rwlck) + Read lock an rwlock + + +

Arguments:

+ + rwlck + A pointer to an rwlock to read lock. + +

This function read locks an rwlock. The calling thread will be + blocked until the rwlock has been read locked. A thread + which currently has read or read/write locked the rwlock may + not lock the same rwlock again. +

+

If you leave an rwlock locked in an emulator thread + when you let the thread out of your control, you will + very likely deadlock the whole emulator. +

+

This function is thread-safe.

+ + + + + interl_drv_rwlock_tryrlock(ErlDrvRWLock *rwlck) + Try to read lock an rwlock + + +

Arguments:

+ + rwlck + A pointer to an rwlock to try to read lock. + +

This function tries to read lock an rwlock. If successful + 0, is returned; otherwise, EBUSY is returned. + A thread which currently has read or read/write locked the + rwlock may not try to lock the same rwlock again. +

+

If you leave an rwlock locked in an emulator thread + when you let the thread out of your control, you will + very likely deadlock the whole emulator. +

+

This function is thread-safe.

+ + + + + voiderl_drv_rwlock_runlock(ErlDrvRWLock *rwlck) + Read unlock an rwlock + + +

Arguments:

+ + rwlck + A pointer to an rwlock to read unlock. + +

This function read unlocks an rwlock. The rwlock currently + has to be read locked by the calling thread. +

+

This function is thread-safe.

+ + + + + voiderl_drv_rwlock_rwlock(ErlDrvRWLock *rwlck) + Read/Write lock an rwlock + + +

Arguments:

+ + rwlck + A pointer to an rwlock to read/write lock. + +

This function read/write locks an rwlock. The calling thread + will be blocked until the rwlock has been read/write locked. + A thread which currently has read or read/write locked the + rwlock may not lock the same rwlock again. +

+

If you leave an rwlock locked in an emulator thread + when you let the thread out of your control, you will + very likely deadlock the whole emulator. +

+

This function is thread-safe.

+ + + + + interl_drv_rwlock_tryrwlock(ErlDrvRWLock *rwlck) + Try to read/write lock an rwlock + + +

Arguments:

+ + rwlck + A pointer to an rwlock to try to read/write lock. + +

This function tries to read/write lock an rwlock. If successful + 0, is returned; otherwise, EBUSY is returned. + A thread which currently has read or read/write locked the + rwlock may not try to lock the same rwlock again. +

+

If you leave an rwlock locked in an emulator thread + when you let the thread out of your control, you will + very likely deadlock the whole emulator. +

+

This function is thread-safe.

+ + + + + voiderl_drv_rwlock_rwunlock(ErlDrvRWLock *rwlck) + Read/Write unlock an rwlock + + +

Arguments:

+ + rwlck + A pointer to an rwlock to read/write unlock. + +

This function read/write unlocks an rwlock. The rwlock + currently has to be read/write locked by the calling thread. +

+

This function is thread-safe.

+ + + + + interl_drv_tsd_key_create(char *name, ErlDrvTSDKey *key) + Create a thread specific data key + + +

Arguments:

+ + name + A string identifying the created key. It will be used + to identify the key in planned future debug + functionality. + + key + A pointer to a thread specific data key variable. + +

This function creates a thread specific data key. On success + 0 is returned; otherwise, an errno value is returned + to indicate the error. The driver creating the key has the + responsibility of destroying it before the driver is unloaded. +

+

This function is thread-safe.

+ + + + + voiderl_drv_tsd_key_destroy(ErlDrvTSDKey key) + Destroy a thread specific data key + + +

Arguments:

+ + key + A thread specific data key to destroy. + +

This function destroys a thread specific data key + previously created by + erl_drv_tsd_key_create(). + All thread specific data using this key in all threads + have to be cleared (see + erl_drv_tsd_set()) + prior to the call to erl_drv_tsd_key_destroy(). +

+

A destroyed key is very likely to be reused soon. + Therefore, if you fail to clear the thread specific + data using this key in a thread prior to destroying + the key, you will very likely get unexpected + errors in other parts of the system. +

+

This function is thread-safe.

+ + + + + voiderl_drv_tsd_set(ErlDrvTSDKey key, void *data) + Set thread specific data + + +

Arguments:

+ + key + A thread specific data key. + data + A pointer to data to associate with key + in calling thread. + + +

This function sets thread specific data associated with + key for the calling thread. You are only allowed to set + thread specific data for threads while they are fully under your + control. For example, if you set thread specific data in a thread + calling a driver call-back function, it has to be cleared, i.e. + set to NULL, before returning from the driver call-back + function. +

+

If you fail to clear thread specific data in an + emulator thread before letting it out of your control, + you might not ever be able to clear this data with + later unexpected errors in other parts of the system as + a result. +

+

This function is thread-safe.

+ + + + + void *erl_drv_tsd_get(ErlDrvTSDKey key) + Get thread specific data + + +

Arguments:

+ + key + A thread specific data key. + +

This function returns the thread specific data + associated with key for the calling thread. + If no data has been associated with key for + the calling thread, NULL is returned. +

+

This function is thread-safe.

+ + + + + interl_drv_putenv(char *key, char *value) + Set the value of an environment variable + + +

Arguments:

+ + key + A null terminated string containing the + name of the environment variable. + value + A null terminated string containing the + new value of the environment variable. + +

This function sets the value of an environment variable. + It returns 0 on success, and a value != 0 on + failure. +

+

The result of passing the empty string ("") as a value + is platform dependent. On some platforms the value of the + variable is set to the empty string, on others, the + environment variable is removed.

+ +

Do not use libc's putenv or similar + C library interfaces from a driver. +

+

This function is thread-safe.

+ + + + + interl_drv_getenv(char *key, char *value, size_t *value_size) + Get the value of an environment variable + + +

Arguments:

+ + key + A null terminated string containing the + name of the environment variable. + value + A pointer to an output buffer. + value_size + A pointer to an integer. The integer is both used for + passing input and output sizes (see below). + + +

This function retrieves the value of an environment variable. + When called, *value_size should contain the size of + the value buffer. On success 0 is returned, + the value of the environment variable has been written to + the value buffer, and *value_size contains the + string length (excluding the terminating null character) of + the value written to the value buffer. On failure, + i.e., no such environment variable was found, a value less than + 0 is returned. When the size of the value + buffer is too small, a value greater than 0 is returned + and *value_size has been set to the buffer size needed. +

+

Do not use libc's getenv or similar + C library interfaces from a driver. +

+

This function is thread-safe.

+ + + + +
+ SEE ALSO +

driver_entry(3), + erl_ddll(3), + erlang(3)

+

An Alternative Distribution Driver (ERTS User's + Guide Ch. 3)

+
+ + diff --git a/erts/doc/src/erl_ext_dist.xml b/erts/doc/src/erl_ext_dist.xml new file mode 100644 index 0000000000..c2d58d1ef1 --- /dev/null +++ b/erts/doc/src/erl_ext_dist.xml @@ -0,0 +1,1014 @@ + + + + +
+ + 2007 + 2007 + Ericsson AB, 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. + + The Initial Developer of the Original Code is Ericsson AB. + + + External Term Format + Kenneth + + 2007-09-21 + PA1 + erl_ext_dist.xml +
+ +
+ Introduction +

+ The external term format is mainly used in the distribution + mechanism of Erlang. +

+

+ Since Erlang has a fixed number of types, there is no need for a + programmer to define a specification for the external format used + within some application. + All Erlang terms has an external representation and the interpretation + of the different terms are application specific. +

+

+ In Erlang the BIF term_to_binary/1,2 is used to convert a + term into the external format. + To convert binary data encoding a term the BIF + + binary_to_term/1 + + is used. +

+

+ The distribution does this implicitly when sending messages across + node boundaries. +

+ +

+ The overall format of the term format is: +

+ + + 1 + 1 + N + + + 131 + Tag + Data + +
+ +

+ When messages are + passed between + connected nodes and a + distribution + header is used, the first byte containing the version + number (131) is omitted from the terms that follow the distribution + header. This since + the version number is implied by the version number in the + distribution header. +

+ +

+ A compressed term looks like this: +

+ + + 1 + 1 + 4 + N + + + 131 + 80 + UncompressedSize + Zlib-compressedData + +
+

+ Uncompressed Size (unsigned 32 bit integer in big-endian byte order) + is the size of the data before it was compressed. + The compressed data has the following format when it has been + expanded: +

+ + + 1 + Uncompressed Size + + + Tag + Data + +
+
+ +
+ + Distribution header +

+ As of erts version 5.7.2 the old atom cache protocol was + dropped and a new one was introduced. This atom cache protocol + introduced the distribution header. Nodes with erts versions + earlier than 5.7.2 can still communicate with new nodes, + but no distribution header and no atom cache will be used.

+

+ The distribution header currently only contains an atom cache + reference section, but could in the future contain more + information. The distribution header precedes one or more Erlang + terms on the external format. For more information see the + documentation of the + protocol between + connected nodes in the + distribution protocol + documentation. +

+

+ ATOM_CACHE_REF + entries with corresponding AtomCacheReferenceIndex in terms + encoded on the external format following a distribution header refers + to the atom cache references made in the distribution header. The range + is 0 <= AtomCacheReferenceIndex < 255, i.e., at most 255 + different atom cache references from the following terms can be made. +

+

+ The distribution header format is: +

+ + + 1 + 1 + 1 + NumberOfAtomCacheRefs/2+1 | 0 + N | 0 + + + 131 + 68 + NumberOfAtomCacheRefs + Flags + AtomCacheRefs + +
+

+ Flags consists of NumberOfAtomCacheRefs/2+1 bytes, + unless NumberOfAtomCacheRefs is 0. If + NumberOfAtomCacheRefs is 0, Flags and + AtomCacheRefs are omitted. Each atom cache reference have + a half byte flag field. Flags corresponding to a specific + AtomCacheReferenceIndex, are located in flag byte number + AtomCacheReferenceIndex/2. Flag byte 0 is the first byte + after the NumberOfAtomCacheRefs byte. Flags for an even + AtomCacheReferenceIndex are located in the least significant + half byte and flags for an odd AtomCacheReferenceIndex are + located in the most significant half byte. +

+

+ The flag field of an atom cache reference has the following + format: +

+ + + 1 bit + 3 bits + + + NewCacheEntryFlag + SegmentIndex + +
+

+ The most significant bit is the NewCacheEntryFlag. If set, + the corresponding cache reference is new. The three least + significant bits are the SegmentIndex of the corresponding + atom cache entry. An atom cache consists of 8 segments each of size + 256, i.e., an atom cache can contain 2048 entries. +

+

+ After flag fields for atom cache references, another half byte flag + field is located which has the following format: +

+ + + 3 bits + 1 bit + + + CurrentlyUnused + LongAtoms + +
+

+ The least significant bit in that half byte is the LongAtoms + flag. If it is set, 2 bytes are used for atom lengths instead of + 1 byte in the distribution header. However, the current emulator + cannot handle long atoms, so it will currently always be 0. +

+

+ After the Flags field follow the AtomCacheRefs. The + first AtomCacheRef is the one corresponding to + AtomCacheReferenceIndex 0. Higher indices follows + in sequence up to index NumberOfAtomCacheRefs - 1. +

+

+ If the NewCacheEntryFlag for the next AtomCacheRef has + been set, a NewAtomCacheRef on the following format will follow: +

+ + + 1 + 1 | 2 + Length + + + InternalSegmentIndex + Length + AtomText + +
+

+ InternalSegmentIndex together with the SegmentIndex + completely identify the location of an atom cache entry in the + atom cache. Length is number of one byte characters that + the atom text consists of. Length is a two byte big endian integer + if the LongAtoms flag has been set, otherwise a one byte + integer. Subsequent CachedAtomRefs with the same + SegmentIndex and InternalSegmentIndex as this + NewAtomCacheRef will refer to this atom until a new + NewAtomCacheRef with the same SegmentIndex + and InternalSegmentIndex appear. +

+

+ If the NewCacheEntryFlag for the next AtomCacheRef + has not been set, a CachedAtomRef on the following format + will follow: +

+ + + 1 + + + InternalSegmentIndex + +
+

+ InternalSegmentIndex together with the SegmentIndex + identify the location of the atom cache entry in the atom cache. + The atom corresponding to this CachedAtomRef is the + latest NewAtomCacheRef preceding this CachedAtomRef + in another previously passed distribution header. +

+
+ +
+ + ATOM_CACHE_REF + + + + 1 + 1 + + + 82 + AtomCacheReferenceIndex + +
+

+ Refers to the atom with AtomCacheReferenceIndex in the + distribution header. +

+
+ +
+ + SMALL_INTEGER_EXT + + + + 1 + 1 + + + 97 + Int + +
+

+ Unsigned 8 bit integer. +

+
+ +
+ + INTEGER_EXT + + + + 1 + 4 + + + 98 + Int + +
+

+ Signed 32 bit integer in big-endian format (i.e. MSB first) +

+
+ +
+ + FLOAT_EXT + + + + 1 + 31 + + + 99 + Float String + +
+

+ A float is stored in string format. the format used in sprintf to + format the float is "%.20e" + (there are more bytes allocated than necessary). + To unpack the float use sscanf with format "%lf". +

+

+ This term is used in minor version 0 of the external format; + it has been superseded by + + NEW_FLOAT_EXT + . +

+
+ +
+ + ATOM_EXT + + + + 1 + 2 + Len + + + 100 + Len + AtomName + +
+

+ An atom is stored with a 2 byte unsigned length in big-endian order, + followed by Len numbers of 8 bit characters that forms the + AtomName. + Note: The maximum allowed value for Len is 255. +

+
+ +
+ + REFERENCE_EXT + + + + 1 + N + 4 + 1 + + + 101 + Node + ID + Creation + +
+

+ Encode a reference object (an object generated with make_ref/0). + The Node term is an encoded atom, i.e. + ATOM_EXT, + SMALL_ATOM_EXT or + ATOM_CACHE_REF. + The ID field contains a big-endian + unsigned integer, + but should be regarded as uninterpreted data + since this field is node specific. + Creation is a byte containing a node serial number that + makes it possible to separate old (crashed) nodes from a new one. +

+

+ In ID, only 18 bits are significant; the rest should be 0. + In Creation, only 2 bits are significant; the rest should be 0. + + See NEW_REFERENCE_EXT. +

+
+ +
+ + PORT_EXT + + + + 1 + N + 4 + 1 + + + 102 + Node + ID + Creation + +
+

+ Encode a port object (obtained form open_port/2). + The ID is a node specific identifier for a local port. + Port operations are not allowed across node boundaries. + The Creation works just like in + REFERENCE_EXT. +

+
+ +
+ + PID_EXT + + + + 1 + N + 4 + 4 + 1 + + + 103 + Node + ID + Serial + Creation + +
+

+ Encode a process identifier object (obtained from spawn/3 or + friends). + The ID and Creation fields works just like in + REFERENCE_EXT, while + the Serial field is used to improve safety. + + In ID, only 15 bits are significant; the rest should be 0. +

+ +
+ +
+ + SMALL_TUPLE_EXT + + + + 1 + 1 + N + + + 104 + Arity + Elements + +
+

+ SMALL_TUPLE_EXT encodes a tuple. The Arity + field is an unsigned byte that determines how many element + that follows in the Elements section. +

+
+ +
+ + LARGE_TUPLE_EXT + + + + 1 + 4 + N + + + 105 + Arity + Elements + +
+

+ Same as + SMALL_TUPLE_EXT + with the exception that Arity is an + unsigned 4 byte integer in big endian format. +

+
+ +
+ + NIL_EXT + + + + 1 + + + 106 + +
+

+ The representation for an empty list, i.e. the Erlang syntax []. +

+
+ +
+ + STRING_EXT + + + + 1 + 2 + Len + + + 107 + Length + Characters + +
+

+ String does NOT have a corresponding Erlang representation, + but is an optimization for sending lists of bytes (integer in + the range 0-255) more efficiently over the distribution. + Since the Length field is an unsigned 2 byte integer + (big endian), implementations must make sure that lists longer than + 65535 elements are encoded as + LIST_EXT. +

+ +
+ +
+ + LIST_EXT + + + + 1 + 4 +   +   + + + 108 + Length + Elements + Tail + +
+ +

+ Length is the number of elements that follows in the + Elements section. Tail is the final tail of + the list; it is + NIL_EXT + for a proper list, but may be anything type if the list is + improper (for instance [a|b]). +

+
+ +
+ + BINARY_EXT + + + + 1 + 4 + Len + + + 109 + Len + Data + +
+

+ Binaries are generated with bit syntax expression or with + list_to_binary/1, + term_to_binary/1, + or as input from binary ports. + The Len length field is an unsigned 4 byte integer + (big endian). +

+
+ +
+ + SMALL_BIG_EXT + + + + 1 + 1 + 1 + n + + + 110 + n + Sign + d(0) ... d(n-1) + +
+

+ Bignums are stored in unary form with a Sign byte + that is 0 if the binum is positive and 1 if is negative. The + digits are stored with the LSB byte stored first. To + calculate the integer the following formula can be used:
+ + B = 256
+ (d0*B^0 + d1*B^1 + d2*B^2 + ... d(N-1)*B^(n-1)) +

+
+ +
+ + LARGE_BIG_EXT + + + + 1 + 4 + 1 + n + + + 111 + n + Sign + d(0) ... d(n-1) + +
+

+ Same as SMALL_BIG_EXT + with the difference that the length field + is an unsigned 4 byte integer. +

+ +
+ +
+ + NEW_REFERENCE_EXT + + + + 1 + 2 + N + 1 + N' + + + 114 + Len + Node + Creation + ID ... + +
+

+ Node and Creation are as in + REFERENCE_EXT. +

+

+ ID contains a sequence of big-endian unsigned integers + (4 bytes each, so N' is a multiple of 4), + but should be regarded as uninterpreted data. +

+

+ N' = 4 * Len. +

+

+ In the first word (four bytes) of ID, only 18 bits are + significant, the rest should be 0. + In Creation, only 2 bits are significant, + the rest should be 0. +

+

+ NEW_REFERENCE_EXT was introduced with distribution version 4. + In version 4, N' should be at most 12. +

+

+ See REFERENCE_EXT). +

+
+ +
+ + SMALL_ATOM_EXT + + + + 1 + 1 + Len + + + 115 + Len + AtomName + +
+

+ An atom is stored with a 1 byte unsigned length, + followed by Len numbers of 8 bit characters that + forms the AtomName. Longer atoms can be represented + by ATOM_EXT. Note + the SMALL_ATOM_EXT was introduced in erts version 5.7.2 and + require a small atom distribution flag exchanged in the distribution + handshake. +

+
+ +
+ + FUN_EXT + + + + 1 + 4 + N1 + N2 + N3 + N4 + N5 + + + 117 + NumFree + Pid + Module + Index + Uniq + Free vars ... + +
+ + Pid + + is a process identifier as in + PID_EXT. + It represents the process in which the fun was created. + + Module + + is an encoded as an atom, using + ATOM_EXT, + SMALL_ATOM_EXT + or ATOM_CACHE_REF. + This is the module that the fun is implemented in. + + Index + + is an integer encoded using + SMALL_INTEGER_EXT + or INTEGER_EXT. + It is typically a small index into the module's fun table. + + Uniq + + is an integer encoded using + SMALL_INTEGER_EXT or + INTEGER_EXT. + Uniq is the hash value of the parse for the fun. + + Free vars + + is NumFree number of terms, each one encoded according + to its type. + + +
+ +
+ + NEW_FUN_EXT + + + + 1 + 4 + 1 + 16 + 4 + 4 + N1 + N2 + N3 + N4 + N5 + + + 112 + Size + Arity + Uniq + Index + NumFree + Module + OldIndex + OldUniq + Pid + Free Vars + +
+

+ This is the new encoding of internal funs: fun F/A and + fun(Arg1,..) -> ... end. +

+ + Size + + is the total number of bytes, including the Size field. + + Arity + + is the arity of the function implementing the fun. + + Uniq + + is the 16 bytes MD5 of the significant parts of the Beam file. + + Index + + is an index number. Each fun within a module has an unique + index. Index is stored in big-endian byte order. + + NumFree + + is the number of free variables. + + Module + + is an encoded as an atom, using + ATOM_EXT, + SMALL_ATOM_EXT or + ATOM_CACHE_REF. + This is the module that the fun is implemented in. + + OldIndex + + is an integer encoded using + SMALL_INTEGER_EXT + or INTEGER_EXT. + It is typically a small index into the module's fun table. + + OldUniq + + is an integer encoded using + SMALL_INTEGER_EXT + or + INTEGER_EXT. + Uniq is the hash value of the parse tree for the fun. + + Pid + + is a process identifier as in + PID_EXT. + It represents the process in which + the fun was created. + + + Free vars + + is NumFree number of terms, each one encoded according + to its type. + + +
+ +
+ + EXPORT_EXT + + + + 1 + N1 + N2 + N3 + + + 113 + Module + Function + Arity + +
+

+ This term is the encoding for external funs: fun M:F/A. +

+

+ Module and Function are atoms + (encoded using ATOM_EXT, + SMALL_ATOM_EXT or + ATOM_CACHE_REF). +

+

+ Arity is an integer encoded using + SMALL_INTEGER_EXT. +

+ +
+ +
+ + BIT_BINARY_EXT + + + + 1 + 4 + 1 + Len + + + 77 + Len + Bits + Data + +
+

+ This term represents a bitstring whose length in bits is not a + multiple of 8 (created using the bit syntax in R12B and later). + The Len field is an unsigned 4 byte integer (big endian). + The Bits field is the number of bits that are used + in the last byte in the data field, + counting from the most significant bit towards the least + significant. +

+ + +
+ +
+ + NEW_FLOAT_EXT + + + + 1 + 8 + + + 70 + IEEE float + +
+

+ A float is stored as 8 bytes in big-endian IEEE format. +

+

+ This term is used in minor version 1 of the external format. +

+
+ + + + + diff --git a/erts/doc/src/erl_ext_fig.gif b/erts/doc/src/erl_ext_fig.gif new file mode 100755 index 0000000000..14d6bbc871 Binary files /dev/null and b/erts/doc/src/erl_ext_fig.gif differ diff --git a/erts/doc/src/erl_ext_fig.ps b/erts/doc/src/erl_ext_fig.ps new file mode 100644 index 0000000000..2501dc3c05 --- /dev/null +++ b/erts/doc/src/erl_ext_fig.ps @@ -0,0 +1,153 @@ +%!PS-Adobe-3.0 EPSF-2.0 +%%BoundingBox: 0 0 600 520 +%%Creator: mscgen 1 +%%EndComments +0.70 0.70 scale +0 0 moveto +0 520 lineto +600 520 lineto +600 0 lineto +closepath +clip +%PageTrailer +%Page: 1 1 +/Helvetica findfont +10 scalefont +setfont +0 520 translate +/mtrx matrix def +/ellipse + { /endangle exch def + /startangle exch def + /ydia exch def + /xdia exch def + /y exch def + /x exch def + /savematrix mtrx currentmatrix def + x y translate + xdia 2 div ydia 2 div scale + 0 0 1 startangle endangle arc + savematrix setmatrix +} def +150 -12 moveto (Client (or Node)) dup stringwidth pop 2 div neg 0 rmoveto show +450 -12 moveto (EPMD) dup stringwidth pop 2 div neg 0 rmoveto show +newpath 150 -20 moveto 150 -45 lineto stroke +newpath 450 -20 moveto 450 -45 lineto stroke +newpath 150 -32 moveto 450 -32 lineto stroke +newpath 450 -32 moveto 440 -38 lineto 440 -26 lineto closepath fill +270 -30 moveto (ALIVE2_REQ) show +newpath 150 -45 moveto 150 -70 lineto stroke +newpath 450 -45 moveto 450 -70 lineto stroke +[2] 0 setdash +newpath 450 -57 moveto 150 -57 lineto stroke +[] 0 setdash +newpath 150 -57 moveto 160 -63 lineto 160 -51 lineto closepath fill +267 -55 moveto (ALIVE2_RESP) show +[2] 0 setdash +newpath 150 -70 moveto 150 -95 lineto stroke +[] 0 setdash +[2] 0 setdash +newpath 450 -70 moveto 450 -95 lineto stroke +[] 0 setdash +newpath 150 -95 moveto 150 -120 lineto stroke +newpath 450 -95 moveto 450 -120 lineto stroke +newpath 150 -107 moveto 450 -107 lineto stroke +newpath 450 -107 moveto 440 -113 lineto 440 -101 lineto closepath fill +253 -105 moveto (ALIVE_CLOSE_REQ) show +[2] 0 setdash +newpath 150 -120 moveto 150 -145 lineto stroke +[] 0 setdash +[2] 0 setdash +newpath 450 -120 moveto 450 -145 lineto stroke +[] 0 setdash +newpath 150 -145 moveto 150 -170 lineto stroke +newpath 450 -145 moveto 450 -170 lineto stroke +newpath 150 -157 moveto 450 -157 lineto stroke +newpath 450 -157 moveto 440 -163 lineto 440 -151 lineto closepath fill +248 -155 moveto (PORT_PLEASE2_REQ) show +newpath 150 -170 moveto 150 -195 lineto stroke +newpath 450 -170 moveto 450 -195 lineto stroke +[2] 0 setdash +newpath 450 -182 moveto 150 -182 lineto stroke +[] 0 setdash +newpath 150 -182 moveto 160 -188 lineto 160 -176 lineto closepath fill +267 -180 moveto (PORT2_RESP) show +[2] 0 setdash +newpath 150 -195 moveto 150 -220 lineto stroke +[] 0 setdash +[2] 0 setdash +newpath 450 -195 moveto 450 -220 lineto stroke +[] 0 setdash +newpath 150 -220 moveto 150 -245 lineto stroke +newpath 450 -220 moveto 450 -245 lineto stroke +newpath 150 -232 moveto 450 -232 lineto stroke +newpath 450 -232 moveto 440 -238 lineto 440 -226 lineto closepath fill +269 -230 moveto (NAMES_REQ) show +newpath 150 -245 moveto 150 -270 lineto stroke +newpath 450 -245 moveto 450 -270 lineto stroke +[2] 0 setdash +newpath 450 -257 moveto 150 -257 lineto stroke +[] 0 setdash +newpath 150 -257 moveto 160 -263 lineto 160 -251 lineto closepath fill +266 -255 moveto (NAMES_RESP) show +[2] 0 setdash +newpath 150 -270 moveto 150 -295 lineto stroke +[] 0 setdash +[2] 0 setdash +newpath 450 -270 moveto 450 -295 lineto stroke +[] 0 setdash +newpath 150 -295 moveto 150 -320 lineto stroke +newpath 450 -295 moveto 450 -320 lineto stroke +newpath 150 -307 moveto 450 -307 lineto stroke +newpath 450 -307 moveto 440 -313 lineto 440 -301 lineto closepath fill +272 -305 moveto (DUMP_REQ) show +newpath 150 -320 moveto 150 -345 lineto stroke +newpath 450 -320 moveto 450 -345 lineto stroke +[2] 0 setdash +newpath 450 -332 moveto 150 -332 lineto stroke +[] 0 setdash +newpath 150 -332 moveto 160 -338 lineto 160 -326 lineto closepath fill +269 -330 moveto (DUMP_RESP) show +[2] 0 setdash +newpath 150 -345 moveto 150 -370 lineto stroke +[] 0 setdash +[2] 0 setdash +newpath 450 -345 moveto 450 -370 lineto stroke +[] 0 setdash +newpath 150 -370 moveto 150 -395 lineto stroke +newpath 450 -370 moveto 450 -395 lineto stroke +newpath 150 -382 moveto 450 -382 lineto stroke +newpath 450 -382 moveto 440 -388 lineto 440 -376 lineto closepath fill +277 -380 moveto (KILL_REQ) show +newpath 150 -395 moveto 150 -420 lineto stroke +newpath 450 -395 moveto 450 -420 lineto stroke +[2] 0 setdash +newpath 450 -407 moveto 150 -407 lineto stroke +[] 0 setdash +newpath 150 -407 moveto 160 -413 lineto 160 -401 lineto closepath fill +274 -405 moveto (KILL_RESP) show +[2] 0 setdash +newpath 150 -420 moveto 150 -445 lineto stroke +[] 0 setdash +[2] 0 setdash +newpath 450 -420 moveto 450 -445 lineto stroke +[] 0 setdash +newpath 150 -445 moveto 150 -470 lineto stroke +newpath 450 -445 moveto 450 -470 lineto stroke +newpath 150 -457 moveto 450 -457 lineto stroke +newpath 450 -457 moveto 440 -463 lineto 440 -451 lineto closepath fill +273 -455 moveto (STOP_REQ) show +newpath 150 -470 moveto 150 -495 lineto stroke +newpath 450 -470 moveto 450 -495 lineto stroke +[2] 0 setdash +newpath 450 -482 moveto 150 -482 lineto stroke +[] 0 setdash +newpath 150 -482 moveto 160 -488 lineto 160 -476 lineto closepath fill +260 -480 moveto (STOP_OK_RESP) show +newpath 150 -495 moveto 150 -520 lineto stroke +newpath 450 -495 moveto 450 -520 lineto stroke +[2] 0 setdash +newpath 450 -507 moveto 150 -507 lineto stroke +[] 0 setdash +newpath 150 -507 moveto 160 -513 lineto 160 -501 lineto closepath fill +250 -505 moveto (STOP_NOTOK_RESP) show diff --git a/erts/doc/src/erl_fix_alloc.fig b/erts/doc/src/erl_fix_alloc.fig new file mode 100644 index 0000000000..57db965a74 --- /dev/null +++ b/erts/doc/src/erl_fix_alloc.fig @@ -0,0 +1,104 @@ +#FIG 3.1 +Landscape +Center +Inches +1200 2 +6 300 1200 2850 3600 +2 1 0 1 -1 7 0 0 -1 0.000 0 0 -1 0 0 4 + 750 3600 750 1200 2325 1200 2325 3600 +2 1 0 1 -1 7 0 0 -1 0.000 0 0 -1 0 0 2 + 750 1500 2325 1500 +2 1 0 1 -1 7 0 0 -1 0.000 0 0 -1 0 0 2 + 750 1800 2325 1800 +2 1 0 2 -1 7 0 0 -1 0.000 0 0 -1 0 0 2 + 375 2100 2775 2100 +4 0 -1 0 0 0 12 0.0000 4 180 1275 900 2025 allocated_blocks\001 +4 0 -1 0 0 0 12 0.0000 4 180 630 1200 1725 free_list\001 +4 0 -1 0 0 0 12 0.0000 4 180 735 1200 1425 item_size\001 +-6 +6 3525 1200 5025 1800 +6 3525 1200 5025 1800 +2 2 0 1 -1 7 0 0 -1 0.000 0 0 -1 0 0 5 + 3525 1200 5025 1200 5025 1800 3525 1800 3525 1200 +2 1 0 1 -1 7 0 0 -1 0.000 0 0 -1 0 0 2 + 3525 1500 5025 1500 +-6 +4 0 -1 0 0 0 12 0.0000 4 105 330 4050 1425 next\001 +4 0 -1 0 0 0 12 0.0000 4 135 405 4050 1725 block\001 +-6 +6 5850 1200 7350 1800 +6 5850 1200 7350 1800 +2 2 0 1 -1 7 0 0 -1 0.000 0 0 -1 0 0 5 + 5850 1200 7350 1200 7350 1800 5850 1800 5850 1200 +2 1 0 1 -1 7 0 0 -1 0.000 0 0 -1 0 0 2 + 5850 1500 7350 1500 +-6 +4 0 -1 0 0 0 12 0.0000 4 105 330 6375 1425 next\001 +4 0 -1 0 0 0 12 0.0000 4 135 405 6375 1725 block\001 +-6 +2 1 1 2 -1 7 0 0 -1 6.000 0 0 7 0 0 2 + 3450 5700 5400 5700 +2 1 0 1 -1 7 0 0 -1 0.000 0 0 7 0 0 4 + 3600 8000 3600 3450 5175 3450 5175 8000 +2 1 1 2 -1 7 0 0 -1 6.000 0 0 -1 0 0 2 + 3525 6900 5325 6900 +2 2 1 0 -1 7 0 0 42 2.000 0 0 -1 0 0 5 + 3675 3525 5100 3525 5100 4425 3675 4425 3675 3525 +2 2 1 0 -1 7 0 0 42 2.000 0 0 -1 0 0 5 + 3675 5775 5100 5775 5100 6825 3675 6825 3675 5775 +2 1 2 1 -1 7 0 0 -1 3.000 0 0 -1 0 0 2 + 3600 4725 5250 4725 +2 1 2 1 -1 7 0 0 -1 3.000 0 0 -1 0 0 2 + 3600 4950 5175 4950 +2 2 2 0 -1 7 0 0 42 1.500 0 0 -1 0 0 5 + 6375 3750 6675 3750 6675 4050 6375 4050 6375 3750 +2 1 0 1 -1 7 0 0 -1 0.000 0 0 -1 1 0 2 + 1 1 1.00 60.00 120.00 + 4275 1800 4275 3400 +2 1 1 2 -1 7 0 0 -1 6.000 0 0 -1 0 0 2 + 3450 4500 5325 4500 +2 1 0 1 -1 7 0 0 -1 0.000 0 0 -1 1 0 2 + 1 1 1.00 60.00 120.00 + 6600 1800 6600 2925 +2 1 0 2 -1 7 0 0 -1 0.000 0 0 -1 1 0 2 + 1 1 2.00 120.00 240.00 + 450 600 750 1125 +3 0 0 1 -1 7 0 0 -1 0.000 0 1 0 3 + 1 1 1.00 60.00 120.00 + 4875 1350 5400 1350 5775 1200 +3 0 0 1 -1 7 0 0 -1 0.000 0 1 0 3 + 1 1 1.00 60.00 120.00 + 7125 1350 7650 1350 8025 1200 +3 2 0 1 -1 7 0 0 -1 0.000 0 1 0 9 + 1 1 1.00 60.00 120.00 + 2175 1650 2475 1650 2625 1725 2775 1875 2775 2025 2775 4275 + 2850 4350 3000 4425 3450 4500 + 0.00 0.00 2346.89 1637.46 2421.89 1637.46 2514.58 1659.34 + 2593.04 1701.97 2665.43 1754.14 2753.11 1822.15 2790.48 1912.37 + 2775.00 1990.83 2775.01 2537.57 2542.79 3714.42 2785.95 4301.43 + 2829.79 4335.43 2881.96 4373.03 2962.69 4412.87 3076.12 4449.75 + 3188.62 4468.50 0.00 0.00 +3 2 0 1 -1 7 0 0 -1 0.000 0 1 0 8 + 1 1 1.00 60.00 120.00 + 5100 4575 5400 4575 5625 4725 5700 4950 5700 6675 5625 6825 + 5475 6900 5175 6975 + 0.00 0.00 5270.86 4558.61 5345.86 4558.61 5465.07 4594.70 + 5582.72 4669.65 5662.08 4773.55 5691.07 4895.01 5764.92 5349.99 + 5796.11 6267.84 5690.66 6714.58 5655.36 6794.64 5594.64 6855.36 + 5511.35 6886.55 5424.73 6918.60 5349.73 6937.35 0.00 0.00 +3 2 0 1 -1 7 0 0 -1 0.000 0 1 0 8 + 1 1 1.00 60.00 120.00 + 2250 1950 2475 1950 2625 1875 2775 1725 2925 1425 3000 1350 + 3150 1275 3450 1200 + 0.00 0.00 2378.92 1959.40 2435.17 1959.40 2514.58 1940.66 + 2593.04 1898.04 2665.43 1845.86 2745.86 1765.43 2821.07 1661.08 + 2878.93 1488.92 2939.57 1404.79 2979.79 1364.57 3031.96 1326.96 + 3113.65 1288.45 3200.27 1256.40 3275.27 1237.65 0.00 0.00 +4 0 -1 0 0 0 12 0.0000 4 180 720 3975 4650 next_free\001 +4 0 -1 0 0 0 12 0.0000 4 180 450 4050 4875 magic\001 +4 0 -1 0 0 2 14 0.0000 4 195 1860 6825 3975 = allocated memory\001 +4 0 -1 0 0 18 12 0.0000 4 135 1305 3675 1125 AllocatedBlock\001 +4 0 -1 0 0 18 12 0.0000 4 135 660 1575 1125 FixItem\001 +4 0 -1 0 0 18 12 0.0000 4 135 1020 2400 4650 FreeHeader\001 +4 0 -1 0 0 2 12 4.7124 4 180 765 5250 3600 item_size\001 +4 0 -1 0 0 2 18 0.0000 4 255 1080 300 525 fix_array\001 diff --git a/erts/doc/src/erl_fix_alloc.gif b/erts/doc/src/erl_fix_alloc.gif new file mode 100644 index 0000000000..c6b41ce801 Binary files /dev/null and b/erts/doc/src/erl_fix_alloc.gif differ diff --git a/erts/doc/src/erl_fix_alloc.ps b/erts/doc/src/erl_fix_alloc.ps new file mode 100644 index 0000000000..bf65d1556c --- /dev/null +++ b/erts/doc/src/erl_fix_alloc.ps @@ -0,0 +1,646 @@ +%!PS-Adobe-2.0 EPSF-2.0 +%%Title: erl_fix_alloc.fig +%%Creator: fig2dev Version 3.1 Patchlevel 2 +%%CreationDate: Tue May 20 11:10:33 1997 +%%For: jocke@akvavit (Joakim Greben|,ETX/B/DUP) +%Magnification: 1.00 +%%Orientation: Portrait +%%BoundingBox: 0 0 506 462 +%%Pages: 0 +%%BeginSetup +%%IncludeFeature: *PageSize A4 +%%EndSetup +%%EndComments +/MyAppDict 100 dict dup begin def +/$F2psDict 200 dict def +$F2psDict begin +$F2psDict /mtrx matrix put +/col-1 {0 setgray} bind def +/col0 {0.000 0.000 0.000 srgb} bind def +/col1 {0.000 0.000 1.000 srgb} bind def +/col2 {0.000 1.000 0.000 srgb} bind def +/col3 {0.000 1.000 1.000 srgb} bind def +/col4 {1.000 0.000 0.000 srgb} bind def +/col5 {1.000 0.000 1.000 srgb} bind def +/col6 {1.000 1.000 0.000 srgb} bind def +/col7 {1.000 1.000 1.000 srgb} bind def +/col8 {0.000 0.000 0.560 srgb} bind def +/col9 {0.000 0.000 0.690 srgb} bind def +/col10 {0.000 0.000 0.820 srgb} bind def +/col11 {0.530 0.810 1.000 srgb} bind def +/col12 {0.000 0.560 0.000 srgb} bind def +/col13 {0.000 0.690 0.000 srgb} bind def +/col14 {0.000 0.820 0.000 srgb} bind def +/col15 {0.000 0.560 0.560 srgb} bind def +/col16 {0.000 0.690 0.690 srgb} bind def +/col17 {0.000 0.820 0.820 srgb} bind def +/col18 {0.560 0.000 0.000 srgb} bind def +/col19 {0.690 0.000 0.000 srgb} bind def +/col20 {0.820 0.000 0.000 srgb} bind def +/col21 {0.560 0.000 0.560 srgb} bind def +/col22 {0.690 0.000 0.690 srgb} bind def +/col23 {0.820 0.000 0.820 srgb} bind def +/col24 {0.500 0.190 0.000 srgb} bind def +/col25 {0.630 0.250 0.000 srgb} bind def +/col26 {0.750 0.380 0.000 srgb} bind def +/col27 {1.000 0.500 0.500 srgb} bind def +/col28 {1.000 0.630 0.630 srgb} bind def +/col29 {1.000 0.750 0.750 srgb} bind def +/col30 {1.000 0.880 0.880 srgb} bind def +/col31 {1.000 0.840 0.000 srgb} bind def + +end +save +-18.0 481.0 translate +1 -1 scale +.9 .9 scale % to make patterns same scale as in xfig + +% This junk string is used by the show operators +/PATsstr 1 string def +/PATawidthshow { % cx cy cchar rx ry string + % Loop over each character in the string + { % cx cy cchar rx ry char + % Show the character + dup % cx cy cchar rx ry char char + PATsstr dup 0 4 -1 roll put % cx cy cchar rx ry char (char) + false charpath % cx cy cchar rx ry char + /clip load PATdraw + % Move past the character (charpath modified the + % current point) + currentpoint % cx cy cchar rx ry char x y + newpath + moveto % cx cy cchar rx ry char + % Reposition by cx,cy if the character in the string is cchar + 3 index eq { % cx cy cchar rx ry + 4 index 4 index rmoveto + } if + % Reposition all characters by rx ry + 2 copy rmoveto % cx cy cchar rx ry + } forall + pop pop pop pop pop % - + currentpoint + newpath + moveto +} bind def +/PATcg { + 7 dict dup begin + /lw currentlinewidth def + /lc currentlinecap def + /lj currentlinejoin def + /ml currentmiterlimit def + /ds [ currentdash ] def + /cc [ currentrgbcolor ] def + /cm matrix currentmatrix def + end +} bind def +% PATdraw - calculates the boundaries of the object and +% fills it with the current pattern +/PATdraw { % proc + save exch + PATpcalc % proc nw nh px py + 5 -1 roll exec % nw nh px py + newpath + PATfill % - + restore +} bind def +% PATfill - performs the tiling for the shape +/PATfill { % nw nh px py PATfill - + PATDict /CurrentPattern get dup begin + setfont + % Set the coordinate system to Pattern Space + PatternGState PATsg + % Set the color for uncolored pattezns + PaintType 2 eq { PATDict /PColor get PATsc } if + % Create the string for showing + 3 index string % nw nh px py str + % Loop for each of the pattern sources + 0 1 Multi 1 sub { % nw nh px py str source + % Move to the starting location + 3 index 3 index % nw nh px py str source px py + moveto % nw nh px py str source + % For multiple sources, set the appropriate color + Multi 1 ne { dup PC exch get PATsc } if + % Set the appropriate string for the source + 0 1 7 index 1 sub { 2 index exch 2 index put } for pop + % Loop over the number of vertical cells + 3 index % nw nh px py str nh + { % nw nh px py str + currentpoint % nw nh px py str cx cy + 2 index show % nw nh px py str cx cy + YStep add moveto % nw nh px py str + } repeat % nw nh px py str + } for + 5 { pop } repeat + end +} bind def + +% PATkshow - kshow with the current pattezn +/PATkshow { % proc string + exch bind % string proc + 1 index 0 get % string proc char + % Loop over all but the last character in the string + 0 1 4 index length 2 sub { + % string proc char idx + % Find the n+1th character in the string + 3 index exch 1 add get % string proe char char+1 + exch 2 copy % strinq proc char+1 char char+1 char + % Now show the nth character + PATsstr dup 0 4 -1 roll put % string proc chr+1 chr chr+1 (chr) + false charpath % string proc char+1 char char+1 + /clip load PATdraw + % Move past the character (charpath modified the current point) + currentpoint newpath moveto + % Execute the user proc (should consume char and char+1) + mark 3 1 roll % string proc char+1 mark char char+1 + 4 index exec % string proc char+1 mark... + cleartomark % string proc char+1 + } for + % Now display the last character + PATsstr dup 0 4 -1 roll put % string proc (char+1) + false charpath % string proc + /clip load PATdraw + neewath + pop pop % - +} bind def +% PATmp - the makepattern equivalent +/PATmp { % patdict patmtx PATmp patinstance + exch dup length 7 add % We will add 6 new entries plus 1 FID + dict copy % Create a new dictionary + begin + % Matrix to install when painting the pattern + TilingType PATtcalc + /PatternGState PATcg def + PatternGState /cm 3 -1 roll put + % Check for multi pattern sources (Level 1 fast color patterns) + currentdict /Multi known not { /Multi 1 def } if + % Font dictionary definitions + /FontType 3 def + % Create a dummy encoding vector + /Encoding 256 array def + 3 string 0 1 255 { + Encoding exch dup 3 index cvs cvn put } for pop + /FontMatrix matrix def + /FontBBox BBox def + /BuildChar { + mark 3 1 roll % mark dict char + exch begin + Multi 1 ne {PaintData exch get}{pop} ifelse % mark [paintdata] + PaintType 2 eq Multi 1 ne or + { XStep 0 FontBBox aload pop setcachedevice } + { XStep 0 setcharwidth } ifelse + currentdict % mark [paintdata] dict + /PaintProc load % mark [paintdata] dict paintproc + end + gsave + false PATredef exec true PATredef + grestore + cleartomark % - + } bind def + currentdict + end % newdict + /foo exch % /foo newlict + definefont % newfont +} bind def +% PATpcalc - calculates the starting point and width/height +% of the tile fill for the shape +/PATpcalc { % - PATpcalc nw nh px py + PATDict /CurrentPattern get begin + gsave + % Set up the coordinate system to Pattern Space + % and lock down pattern + PatternGState /cm get setmatrix + BBox aload pop pop pop translate + % Determine the bounding box of the shape + pathbbox % llx lly urx ury + grestore + % Determine (nw, nh) the # of cells to paint width and height + PatHeight div ceiling % llx lly urx qh + 4 1 roll % qh llx lly urx + PatWidth div ceiling % qh llx lly qw + 4 1 roll % qw qh llx lly + PatHeight div floor % qw qh llx ph + 4 1 roll % ph qw qh llx + PatWidth div floor % ph qw qh pw + 4 1 roll % pw ph qw qh + 2 index sub cvi abs % pw ph qs qh-ph + exch 3 index sub cvi abs exch % pw ph nw=qw-pw nh=qh-ph + % Determine the starting point of the pattern fill + %(px, py) + 4 2 roll % nw nh pw ph + PatHeight mul % nw nh pw py + exch % nw nh py pw + PatWidth mul exch % nw nh px py + end +} bind def + +% Save the original routines so that we can use them later on +/oldfill /fill load def +/oldeofill /eofill load def +/oldstroke /stroke load def +/oldshow /show load def +/oldashow /ashow load def +/oldwidthshow /widthshow load def +/oldawidthshow /awidthshow load def +/oldkshow /kshow load def + +% These defs are necessary so that subsequent procs don't bind in +% the originals +/fill { oldfill } bind def +/eofill { oldeofill } bind def +/stroke { oldstroke } bind def +/show { oldshow } bind def +/ashow { oldashow } bind def +/widthshow { oldwidthshow } bind def +/awidthshow { oldawidthshow } bind def +/kshow { oldkshow } bind def +/PATredef { + MyAppDict begin + { + /fill { /clip load PATdraw newpath } bind def + /eofill { /eoclip load PATdraw newpath } bind def + /stroke { PATstroke } bind def + /show { 0 0 null 0 0 6 -1 roll PATawidthshow } bind def + /ashow { 0 0 null 6 3 roll PATawidthshow } + bind def + /widthshow { 0 0 3 -1 roll PATawidthshow } + bind def + /awidthshow { PATawidthshow } bind def + /kshow { PATkshow } bind def + } { + /fill { oldfill } bind def + /eofill { oldeofill } bind def + /stroke { oldstroke } bind def + /show { oldshow } bind def + /ashow { oldashow } bind def + /widthshow { oldwidthshow } bind def + /awidthshow { oldawidthshow } bind def + /kshow { oldkshow } bind def + } ifelse + end +} bind def +false PATredef +% Conditionally define setcmykcolor if not available +/setcmykcolor where { pop } { + /setcmykcolor { + 1 sub 4 1 roll + 3 { + 3 index add neg dup 0 lt { pop 0 } if 3 1 roll + } repeat + setrgbcolor - pop + } bind def +} ifelse +/PATsc { % colorarray + aload length % c1 ... cn length + dup 1 eq { pop setgray } { 3 eq { setrgbcolor } { setcmykcolor + } ifelse } ifelse +} bind def +/PATsg { % dict + begin + lw setlinewidth + lc setlinecap + lj setlinejoin + ml setmiterlimit + ds aload pop setdash + cc aload pop setrgbcolor + cm setmatrix + end +} bind def + +/PATDict 3 dict def +/PATsp { + true PATredef + PATDict begin + /CurrentPattern exch def + % If it's an uncolored pattern, save the color + CurrentPattern /PaintType get 2 eq { + /PColor exch def + } if + /CColor [ currentrgbcolor ] def + end +} bind def +% PATstroke - stroke with the current pattern +/PATstroke { + countdictstack + save + mark + { + currentpoint strokepath moveto + PATpcalc % proc nw nh px py + clip newpath PATfill + } stopped { + (*** PATstroke Warning: Path is too complex, stroking + with gray) = + cleartomark + restore + countdictstack exch sub dup 0 gt + { { end } repeat } { pop } ifelse + gsave 0.5 setgray oldstroke grestore + } { pop restore pop } ifelse + newpath +} bind def +/PATtcalc { % modmtx tilingtype PATtcalc tilematrix + % Note: tiling types 2 and 3 are not supported + gsave + exch concat % tilingtype + matrix currentmatrix exch % cmtx tilingtype + % Tiling type 1 and 3: constant spacing + 2 ne { + % Distort the pattern so that it occupies + % an integral number of device pixels + dup 4 get exch dup 5 get exch % tx ty cmtx + XStep 0 dtransform + round exch round exch % tx ty cmtx dx.x dx.y + XStep div exch XStep div exch % tx ty cmtx a b + 0 YStep dtransform + round exch round exch % tx ty cmtx a b dy.x dy.y + YStep div exch YStep div exch % tx ty cmtx a b c d + 7 -3 roll astore % { a b c d tx ty } + } if + grestore +} bind def +/PATusp { + false PATredef + PATDict begin + CColor PATsc + end +} bind def + +% right30 +11 dict begin +/PaintType 1 def +/PatternType 1 def +/TilingType 1 def +/BBox [0 0 1 1] def +/XStep 1 def +/YStep 1 def +/PatWidth 1 def +/PatHeight 1 def +/Multi 2 def +/PaintData [ + { clippath } bind + { 32 16 true [ 32 0 0 -16 0 16 ] + {<00030003000c000c0030003000c000c0030003000c000c00 + 30003000c000c00000030003000c000c0030003000c000c0 + 030003000c000c0030003000c000c000>} + imagemask } bind +] def +/PaintProc { + pop + exec fill +} def +currentdict +end +/P2 exch def +1.1111 1.1111 scale %restore scale + +/cp {closepath} bind def +/ef {eofill} bind def +/gr {grestore} bind def +/gs {gsave} bind def +/sa {save} bind def +/rs {restore} bind def +/l {lineto} bind def +/m {moveto} bind def +/rm {rmoveto} bind def +/n {newpath} bind def +/s {stroke} bind def +/sh {show} bind def +/slc {setlinecap} bind def +/slj {setlinejoin} bind def +/slw {setlinewidth} bind def +/srgb {setrgbcolor} bind def +/rot {rotate} bind def +/sc {scale} bind def +/sd {setdash} bind def +/ff {findfont} bind def +/sf {setfont} bind def +/scf {scalefont} bind def +/sw {stringwidth} bind def +/tr {translate} bind def +/tnt {dup dup currentrgbcolor + 4 -2 roll dup 1 exch sub 3 -1 roll mul add + 4 -2 roll dup 1 exch sub 3 -1 roll mul add + 4 -2 roll dup 1 exch sub 3 -1 roll mul add srgb} + bind def +/shd {dup dup currentrgbcolor 4 -2 roll mul 4 -2 roll mul + 4 -2 roll mul srgb} bind def + /DrawSplineSection { + /y3 exch def + /x3 exch def + /y2 exch def + /x2 exch def + /y1 exch def + /x1 exch def + /xa x1 x2 x1 sub 0.666667 mul add def + /ya y1 y2 y1 sub 0.666667 mul add def + /xb x3 x2 x3 sub 0.666667 mul add def + /yb y3 y2 y3 sub 0.666667 mul add def + x1 y1 lineto + xa ya xb yb x3 y3 curveto + } def + +/$F2psBegin {$F2psDict begin /$F2psEnteredState save def} def +/$F2psEnd {$F2psEnteredState restore end} def +%%EndProlog + +$F2psBegin +10 setmiterlimit +n 0 842 m 0 0 l 595 0 l 595 842 l cp clip + 0.06000 0.06000 sc +7.500 slw +% Polyline +n 750 3600 m 750 1200 l 2325 1200 l 2325 3600 l gs col-1 s gr +% Polyline +n 750 1500 m 2325 1500 l gs col-1 s gr +% Polyline +n 750 1800 m 2325 1800 l gs col-1 s gr +15.000 slw +% Polyline +n 375 2100 m 2775 2100 l gs col-1 s gr +/Times-Roman ff 180.00 scf sf +900 2025 m +gs 1 -1 sc (allocated_blocks) col-1 sh gr +/Times-Roman ff 180.00 scf sf +1200 1725 m +gs 1 -1 sc (free_list) col-1 sh gr +/Times-Roman ff 180.00 scf sf +1200 1425 m +gs 1 -1 sc (item_size) col-1 sh gr +7.500 slw +% Polyline +n 3525 1200 m 5025 1200 l 5025 1800 l 3525 1800 l cp gs col-1 s gr +% Polyline +n 3525 1500 m 5025 1500 l gs col-1 s gr +/Times-Roman ff 180.00 scf sf +4050 1425 m +gs 1 -1 sc (next) col-1 sh gr +/Times-Roman ff 180.00 scf sf +4050 1725 m +gs 1 -1 sc (block) col-1 sh gr +% Polyline +n 5850 1200 m 7350 1200 l 7350 1800 l 5850 1800 l cp gs col-1 s gr +% Polyline +n 5850 1500 m 7350 1500 l gs col-1 s gr +/Times-Roman ff 180.00 scf sf +6375 1425 m +gs 1 -1 sc (next) col-1 sh gr +/Times-Roman ff 180.00 scf sf +6375 1725 m +gs 1 -1 sc (block) col-1 sh gr +15.000 slw +% Polyline + [100.0] 0 sd +n 3450 5700 m 5400 5700 l gs col-1 s gr [] 0 sd +7.500 slw +% Polyline +n 3600 8000 m 3600 3450 l 5175 3450 l 5175 8000 l gs col-1 s gr +15.000 slw +% Polyline + [100.0] 0 sd +n 3525 6900 m 5325 6900 l gs col-1 s gr [] 0 sd +0.000 slw +% Polyline + [33.3] 0 sd +n 3675 3525 m 5100 3525 l 5100 4425 l 3675 4425 l cp gs /PC [[1.00 1.00 1.00] [0.00 0.00 0.00]] def +15.00 15.00 sc P2 [16 0 0 -8 245.00 235.00] PATmp PATsp ef gr PATusp [] 0 sd +% Polyline + [33.3] 0 sd +n 3675 5775 m 5100 5775 l 5100 6825 l 3675 6825 l cp gs /PC [[1.00 1.00 1.00] [0.00 0.00 0.00]] def +15.00 15.00 sc P2 [16 0 0 -8 245.00 385.00] PATmp PATsp ef gr PATusp [] 0 sd +7.500 slw +% Polyline + [15 50.0] 50.0 sd +n 3600 4725 m 5250 4725 l gs col-1 s gr [] 0 sd +% Polyline + [15 50.0] 50.0 sd +n 3600 4950 m 5175 4950 l gs col-1 s gr [] 0 sd +0.000 slw +% Polyline + [15 25.0] 25.0 sd +n 6375 3750 m 6675 3750 l 6675 4050 l 6375 4050 l cp gs /PC [[1.00 1.00 1.00] [0.00 0.00 0.00]] def +15.00 15.00 sc P2 [16 0 0 -8 425.00 250.00] PATmp PATsp ef gr PATusp [] 0 sd +7.500 slw +% Polyline +gs clippath +4305 3253 m 4275 3373 l 4245 3253 l 4245 3415 l 4305 3415 l cp clip +n 4275 1800 m 4275 3400 l gs col-1 s gr gr + +% arrowhead +n 4305 3253 m 4275 3373 l 4245 3253 l 4275 3253 l 4305 3253 l cp gs 0.00 setgray ef gr col-1 s +15.000 slw +% Polyline + [100.0] 0 sd +n 3450 4500 m 5325 4500 l gs col-1 s gr [] 0 sd +7.500 slw +% Polyline +gs clippath +6630 2778 m 6600 2898 l 6570 2778 l 6570 2940 l 6630 2940 l cp clip +n 6600 1800 m 6600 2925 l gs col-1 s gr gr + +% arrowhead +n 6630 2778 m 6600 2898 l 6570 2778 l 6600 2778 l 6630 2778 l cp gs 0.00 setgray ef gr col-1 s +15.000 slw +% Polyline +gs clippath +656 840 m 723 1078 l 552 900 l 713 1181 l 817 1121 l cp clip +n 450 600 m 750 1125 l gs col-1 s gr gr + +% arrowhead +n 656 840 m 723 1078 l 552 900 l 604 870 l 656 840 l cp gs 0.00 setgray ef gr col-1 s +% Open spline +gs clippath +5627 1227 m 5749 1210 l 5650 1282 l 5800 1222 l 5778 1167 l cp clip +7.500 slw +n 4875.0 1350.0 m 5137.5 1350.0 l + 5137.5 1350.0 5400.0 1350.0 5587.5 1275.0 DrawSplineSection + 5775.0 1200.0 l gs col-1 s gr + gr + +% arrowhead +n 5627 1227 m 5749 1210 l 5650 1282 l 5639 1255 l 5627 1227 l cp gs 0.00 setgray ef gr col-1 s +% Open spline +gs clippath +7877 1227 m 7999 1210 l 7900 1282 l 8050 1222 l 8028 1167 l cp clip +n 7125.0 1350.0 m 7387.5 1350.0 l + 7387.5 1350.0 7650.0 1350.0 7837.5 1275.0 DrawSplineSection + 8025.0 1200.0 l gs col-1 s gr + gr + +% arrowhead +n 7877 1227 m 7999 1210 l 7900 1282 l 7889 1255 l 7877 1227 l cp gs 0.00 setgray ef gr col-1 s +% Interp Spline +gs clippath +3308 4453 m 3423 4496 l 3300 4512 l 3461 4532 l 3468 4472 l cp clip +n 2175 1650 m + 2346.9 1637.5 2421.9 1637.5 2475 1650 curveto + 2514.6 1659.3 2593.0 1702.0 2625 1725 curveto + 2665.4 1754.1 2753.1 1822.2 2775 1875 curveto + 2790.5 1912.4 2775.0 1990.8 2775 2025 curveto + 2775.0 2537.6 2542.8 3714.4 2775 4275 curveto + 2785.9 4301.4 2829.8 4335.4 2850 4350 curveto + 2882.0 4373.0 2962.7 4412.9 3000 4425 curveto + 3076.1 4449.8 3188.6 4468.5 3450 4500 curveto + gs col-1 s gr + gr + +% arrowhead +n 3308 4453 m 3423 4496 l 3300 4512 l 3304 4483 l 3308 4453 l cp gs 0.00 setgray ef gr col-1 s +% Interp Spline +gs clippath +5325 6973 m 5201 6969 l 5312 6914 l 5154 6949 l 5167 7007 l cp clip +n 5100 4575 m + 5270.9 4558.6 5345.9 4558.6 5400 4575 curveto + 5465.1 4594.7 5582.7 4669.6 5625 4725 curveto + 5662.1 4773.6 5691.1 4895.0 5700 4950 curveto + 5764.9 5350.0 5796.1 6267.8 5700 6675 curveto + 5690.7 6714.6 5655.4 6794.6 5625 6825 curveto + 5594.6 6855.4 5511.4 6886.6 5475 6900 curveto + 5424.7 6918.6 5349.7 6937.4 5175 6975 curveto + gs col-1 s gr + gr + +% arrowhead +n 5325 6973 m 5201 6969 l 5312 6914 l 5319 6944 l 5325 6973 l cp gs 0.00 setgray ef gr col-1 s +% Interp Spline +gs clippath +3300 1202 m 3423 1205 l 3313 1261 l 3471 1226 l 3458 1168 l cp clip +n 2250 1950 m + 2378.9 1959.4 2435.2 1959.4 2475 1950 curveto + 2514.6 1940.7 2593.0 1898.0 2625 1875 curveto + 2665.4 1845.9 2745.9 1765.4 2775 1725 curveto + 2821.1 1661.1 2878.9 1488.9 2925 1425 curveto + 2939.6 1404.8 2979.8 1364.6 3000 1350 curveto + 3032.0 1327.0 3113.7 1288.5 3150 1275 curveto + 3200.3 1256.4 3275.3 1237.7 3450 1200 curveto + gs col-1 s gr + gr + +% arrowhead +n 3300 1202 m 3423 1205 l 3313 1261 l 3306 1231 l 3300 1202 l cp gs 0.00 setgray ef gr col-1 s +/Times-Roman ff 180.00 scf sf +3975 4650 m +gs 1 -1 sc (next_free) col-1 sh gr +/Times-Roman ff 180.00 scf sf +4050 4875 m +gs 1 -1 sc (magic) col-1 sh gr +/Times-Bold ff 210.00 scf sf +6825 3975 m +gs 1 -1 sc (= allocated memory) col-1 sh gr +/Helvetica-Bold ff 180.00 scf sf +3675 1125 m +gs 1 -1 sc (AllocatedBlock) col-1 sh gr +/Helvetica-Bold ff 180.00 scf sf +1575 1125 m +gs 1 -1 sc (FixItem) col-1 sh gr +/Helvetica-Bold ff 180.00 scf sf +2400 4650 m +gs 1 -1 sc (FreeHeader) col-1 sh gr +/Times-Bold ff 180.00 scf sf +5250 3600 m +gs 1 -1 sc 270.0 rot (item_size) col-1 sh gr +/Times-Bold ff 270.00 scf sf +300 525 m +gs 1 -1 sc (fix_array) col-1 sh gr +$F2psEnd +rs +end diff --git a/erts/doc/src/erl_nif.xml b/erts/doc/src/erl_nif.xml new file mode 100644 index 0000000000..c636d65ef3 --- /dev/null +++ b/erts/doc/src/erl_nif.xml @@ -0,0 +1,351 @@ + + + + +
+ + 20012009 + Ericsson AB. 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. + + + + erl_nif + Sverker Eriksson + Sverker Eriksson + 1 + + + 2009-11-17 + PA1 + erl_nif.xml +
+ erl_nif + API functions for an Erlang NIF library + +

The NIF concept is introduced in R13B03 as an + EXPERIMENTAL feature. The interfaces may be changed in any way + in coming releases. The API introduced in this release is very + sparse and contains only the most basic functions to read and + write Erlang terms. +

+ +

A NIF library contains native implementation of some functions + of an erlang module. The native implemented functions (NIFs) are + called like any other functions without any difference to the + caller. Each NIF must also have an implementation in Erlang that + will be invoked if the function is called before the NIF library + has been successfully loaded. A typical such stub implementation + is to throw an exception. But it can also be used as a fallback + implementation if the NIF library is not implemented for some + architecture.

+

A minimal example of a NIF library can look like this:

+

+ +/* niftest.c */ +#include "erl_nif.h" + +static ERL_NIF_TERM hello(ErlNifEnv* env) +{ + return enif_make_string(env, "Hello world!"); +} + +static ErlNifFunc nif_funcs[] = +{ + {"hello", 0, hello} +}; + +ERL_NIF_INIT(niftest,nif_funcs,NULL,NULL,NULL,NULL) + + +

and the erlang module would have to look something like + this:

+

+ +-module(niftest). + +-export([init/0, hello/0]). + +init() -> + erlang:load_nif("./niftest", 0). + +hello() -> + "NIF library not loaded". + +

and compile and test something like this (on Linux):

+

+ +$> gcc -fPIC -shared -o niftest.so niftest.c -I $ERL_ROOT/usr/include/ +$> erl + +1> c(niftest). +{ok,niftest} +2> niftest:hello(). +"NIF library not loaded" +3> niftest:init(). +ok +4> niftest:hello(). +"Hello world!" + + +

A better solution for a real module is to take advantage of + the new attribute on_load to automatically load the NIF + library when the module is loaded.

+

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 + new code will have to load its own NIF library (or maybe choose not + to). The new code version can however choose to load the exact + same NIF library as the old code if it wants to. Sharing the same + dynamic library will mean that static data defined by the library + will be shared as well. To avoid unintentionally shared static + data, each Erlang module code can keep its own private data. This + global private data can be set when the NIF library is loaded and + then retrieved by calling enif_get_data().

+

There is currently 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 can also be unloaded by replacing it with another + version of the library by a second call to + erlang:load_nif/2 from the same module code.

+ + +
+ INITIALIZATION + + ERL_NIF_INIT(MODULE, ErlNifFunc funcs[], load, reload, upgrade, unload) +

This is the magic macro to initialize a NIF library. It + should be evaluated in global file scope.

+

MODULE is the name of the Erlang module as an + identifier without string quotations. It will be stringified by + the macro.

+

funcs is a static array of function descriptors for + all the implemented NIFs in this library.

+

load, reload, upgrade and unload + are pointers to functions. One of load, reload or + upgrade will be called to initialize the library. + unload is called to release the library. They are all + described individually below.

+ + + int (*load)(ErlNifEnv* env, void** priv_data, ERL_NIF_TERM load_info) +

load is called when the NIF library is loaded + and there is no previously loaded library for this module.

+

*priv_data can be set to point to some private data + that the library needs in able to keep a state between NIF + calls. enif_get_data() will return this pointer.

+

load_info is the second argument to erlang:load_nif/2.

+

The library will fail to load if load returns + anything other than 0. load can be NULL in case no + initialization is needed.

+ + + int (*reload)(ErlNifEnv* env, void** priv_data, ERL_NIF_TERM load_info) +

reload is called when the NIF library is loaded + and there is already a previously loaded library for this + module code.

+

Works the same as load. The only difference is that + *priv_data already contains the value set by the + previous call to load or reload.

+

The library will fail to load if reload returns + anything other than 0 or if reload is NULL.

+ + + int (*upgrade)(ErlNifEnv* env, void** priv_data, void** old_priv_data, ERL_NIF_TERM load_info) +

upgrade is called when the NIF library is loaded + and there is no previously loaded library for this module + code, BUT there is old code of this module with a + loaded NIF library.

+

Works the same as load. The only difference is that + *old_priv_data already contains the value set by the + last call to load or reload for the old module + code. It is allowed to write to both *priv_data and + *old_priv_data.

+

The library will fail to load if upgrade returns + anything other than 0 or if upgrade is NULL.

+ + + void (*unload)(ErlNifEnv* env, void* priv_data) +

unload is called when the module code that + the NIF library belongs to is purged as old. New code + of the same module may or may not exist.

+ + + + +
+ +
+ DATA TYPES + + + ErlDrvEnv + +

ErlNifEnv 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 ErlNifEnv pointer is only valid until + the function, where is what supplied as argument, + returns. There is thus useless and dangerous to store ErlNifEnv + pointers in between NIF calls.

+ + ErlNifFunc + +

+ +typedef struct { + const char* name; + unsigned arity; + ERL_NIF_TERM (*fptr)(ErlNifEnv* env, ...); +} ErlNifFunc; + +

Describes a NIF by its name, arity and implementation. + fptr is a pointer to the function that implements the + NIF. The number of arguments must match the arity. A NIF of + arity 2 will thus look like:

+

+ +ERL_NIF_TERM my_nif(ErlNifEnv* env, ERL_NIF_TERM arg1, ERL_NIF_TERM arg2) +{ + /* ... */ +} + +

The maximum allowed arity for a NIF is 3 in current implementation.

+ + ErlNifBinary + +

+ +typedef struct { + unsigned size; + unsigned char* data; +} ErlNifBinary; + +

ErlNifBinary contains transient information about an + inspected binary term. data is a pointer to a buffer + of size bytes with the raw content of the binary.

+ + ERL_NIF_TERM + +

Variables of type ERL_NIF_TERM can refere 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 ERL_NIF_TERM is + only valid until the NIF call, where it was obtained, + returns.

+ + +
+ + + void*enif_get_data(ErlNifEnv* env) + Get the private data of a NIF library +

Returns the pointer to the private data that was set by load, reload or upgrade.

 + + void*enif_alloc(ErlNifEnv* env, size_t size) + Allocate dynamic memory. +

Allocate memory of size bytes.

 + + voidenif_free(ErlNifEnv* env, void* ptr) + Free dynamic memory +

Free memory allocated by enif_alloc.

 + + intenif_is_binary(ErlNifEnv* env, ERL_NIF_TERM term) + Determine if a term is a binary +

Return true if term is a binary

 + + intenif_inspect_binary(ErlNifEnv* env, ERL_NIF_TERM bin_term, ErlNifBinary* bin) + Inspect the content of a binary +

Initialize the structure pointed to by bin with + transient information about the binary term + bin_term. Return false if bin_term is not a binary.

 + + intenif_alloc_binary(ErlNifEnv* env, unsigned size, ErlNifBinary* bin) + Create a new binary. +

Allocate a new binary of size of size + bytes. Initialize the structure pointed to by bin to + refer to the allocated binary.

 + + voidenif_release_binary(ErlNifEnv* env, ErlNifBinary* bin) + Release a binary. +

Release a binary obtained from enif_alloc_binary or enif_inspect_binary.

 + + intenif_get_int(ErlNifEnv* env, ERL_NIF_TERM term, int* ip) + Read an integer term. +

Set *ip to the integer value of + term or return false if term is not an integer or is + outside the bounds of type int

 + + intenif_get_ulong(ErlNifEnv* env, ERL_NIF_TERM term, unsigned long* ip) + Read an unsigned long integer +

Set *ip to the unsigned long integer value of + term or return false if term is not an unsigned + integer or is outside the bounds of type unsigned long

 + + intenif_get_list_cell(ErlNifEnv* env, ERL_NIF_TERM list, ERL_NIF_TERM* head, ERL_NIF_TERM* tail) + Get head and tail from a list +

Set *head and *tail from + list or return false if list is not a non-empty + list.

 + + ERL_NIF_TERMenif_make_binary(ErlNifEnv* env, ErlNifBinary* bin) + Make a binary term. +

Make a binary term from bin. Will also release + the binary.

 + + ERL_NIF_TERMenif_make_badarg(ErlNifEnv* env) + Make a badarg exception. +

Make a badarg exception to be returned from a NIF.

 + + ERL_NIF_TERMenif_make_int(ErlNifEnv* env, int i) + Create an integer term +

Create an integer term.

 + + ERL_NIF_TERMenif_make_ulong(ErlNifEnv* env, unsigned long i) + Create an integer term from an unsigned long int +

Create an integer term from an unsigned long int.

 + + ERL_NIF_TERMenif_make_atom(ErlNifEnv* env, const char* name) + Create an atom term +

Create an atom term from the C-string name. Atom + terms may be saved and used between NIF calls.

 + + ERL_NIF_TERMenif_make_tuple(ErlNifEnv* env, unsigned cnt, ...) + Create a tuple term. +

Create a tuple term of arity cnt. Expects + cnt number of arguments (after cnt) of type ERL_NIF_TERM as the + elements of the tuple.

 + + ERL_NIF_TERMenif_make_list(ErlNifEnv* env, unsigned cnt, ...) + Create a list term. +

Create an ordinary list term of length cnt. Expects + cnt number of arguments (after cnt) of type ERL_NIF_TERM as the + elements of the list. An empty list is returned if cnt is 0.

 + + ERL_NIF_TERMenif_make_list_cell(ErlNifEnv* env, ERL_NIF_TERM head, ERL_NIF_TERM tail) + Create a list cell. +

Create a list cell [head | tail].

 + + ERL_NIF_TERMenif_make_string(ErlNifEnv* env, const char* string) + Create a string. +

Creates a list containing the characters of the + C-string string.

 + + +
+ SEE ALSO +

load_nif(3)

+
+ + diff --git a/erts/doc/src/erl_prim_loader.xml b/erts/doc/src/erl_prim_loader.xml new file mode 100644 index 0000000000..ccaa9b725f --- /dev/null +++ b/erts/doc/src/erl_prim_loader.xml @@ -0,0 +1,251 @@ + + + + +
+ + 19962009 + Ericsson AB. 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. + + + + erl_prim_loader + + + + + erl_prim_loader.xml +
+ erl_prim_loader + Low Level Erlang Loader + +

erl_prim_loader is used to load all Erlang modules into + the system. The start script is also fetched with this low level + loader.

+

erl_prim_loader knows about the environment and how to + fetch modules. The loader could, for example, fetch files using + the file system (with absolute file names as input), or a + database (where the binary format of a module is stored).

+

The -loader Loader command line flag can be used to + choose the method used by the erl_prim_loader. Two + Loader methods are supported by the Erlang runtime system: + efile and inet. If another loader is required, then + it has to be implemented by the user. The Loader provided + by the user must fulfill the protocol defined below, and it is + started with the erl_prim_loader by evaluating + open_port({spawn,Loader},[binary]).

+ +

The support for loading of code from archive files is + experimental. The sole purpose of releasing it before it is ready + is to obtain early feedback. The file format, semantics, + interfaces etc. may be changed in a future release. The functions + list_dir/1 and read_file_info/1 as well as the flag + -loader_debug are also experimental

 + + + + + start(Id, Loader, Hosts) -> {ok, Pid} | {error, What} + Start the Erlang low level loader + + Id = term() + Loader = atom() | string() + Hosts = [Host] + Host = atom() + Pid = pid() + What = term() + + +

Starts the Erlang low level loader. This function is called + by the init process (and module). The init + process reads the command line flags -id Id, + -loader Loader, and -hosts Hosts. These are + the arguments supplied to the start/3 function.

+

If -loader is not given, the default loader is + efile which tells the system to read from the file + system.

+

If -loader is inet, the -id Id, + -hosts Hosts, and -setcookie Cookie flags must + also be supplied. Hosts identifies hosts which this + node can contact in order to load modules. One Erlang + runtime system with a erl_boot_server process must be + started on each of hosts given in Hosts in order to + answer the requests. See erl_boot_server(3).

+

If -loader is something else, the given port program + is started. The port program is supposed to follow + the protocol specified below.

+ + + + get_file(Filename) -> {ok, Bin, FullName} | error + Get a file + + Filename = string() + Bin = binary() + FullName = string() + + +

This function fetches a file using the low level loader. + Filename is either an absolute file name or just the name + of the file, for example "lists.beam". 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. + FullName is the complete name of the fetched file. + Bin is the contents of the file as a binary.

+ +

The Filename can also be a file in an archive. For example + /otp/root/lib/mnesia-4.4.7.ez/mnesia-4.4.7/ebin/mnesia_backup.beam + See code(3) about archive files.

+ + + + get_path() -> {ok, Path} + Get the path set in the loader + + Path = [Dir] + Dir = string() + + +

This function gets the path set in the loader. The path is + set by the init process according to information found + in the start script.

+ + + + list_dir(Dir) -> {ok, Filenames} | error + List files in a directory + + Dir = name() + Filenames = [Filename] + Filename = string() + + +

Lists all the files in a directory. Returns + {ok, Filenames} if successful. Otherwise, it returns + error. Filenames is a list of + the names of all the files in the directory. The names are + not sorted.

+

The Dir can also be a directory in an archive. For example + /otp/root/lib/mnesia-4.4.7.ez/mnesia-4.4.7/ebin + See code(3) about archive files.

+ + + + read_file_info(Filename) -> {ok, FileInfo} | error + Get information about a file + + Filename = name() + FileInfo = #file_info{} + + +

Retrieves information about a file. Returns + {ok, FileInfo} if successful, otherwise + error. FileInfo is a record + file_info, defined in the Kernel include file + file.hrl. Include the following directive in the module + from which the function is called:

+ +-include_lib("kernel/include/file.hrl"). +

See file(3) for more info about + the record file_info.

+

The Filename can also be a file in an archive. For example + /otp/root/lib/mnesia-4.4.7.ez/mnesia-4.4.7/ebin/mnesia_backup.beam + See code(3) about archive files.

+ + + + set_path(Path) -> ok + Set the path of the loader + + Path = [Dir] + Dir = string() + + +

This function sets the path of the loader if init + interprets a path command in the start script.

+ + + + +
+ Protocol +

The following protocol must be followed if a user provided + loader port program is used. The Loader port program is + started with the command + open_port({spawn,Loader},[binary]). The protocol is as + follows:

+ 
+Function          Send               Receive
+-------------------------------------------------------------
+get_file          [102 | FileName]   [121 | BinaryFile] (on success)
+                                     [122]              (failure)
+
+stop              eof                terminate
+
+ +
+ Command Line Flags +

The erl_prim_loader module interprets the following + command line flags:

+ + -loader Loader + +

Specifies the name of the loader used by + erl_prim_loader. Loader can be efile + (use the local file system), or inet (load using + the boot_server on another Erlang node). If + Loader is user defined, the defined Loader port + program is started.

+

If the -loader flag is omitted, it defaults to + efile.

+ + -loader_debug + +

Makes the efile loader write some debug information, + such as the reason for failures, while it handles files.

+ + -hosts Hosts + +

Specifies which other Erlang nodes the inet loader + can use. This flag is mandatory if the -loader inet + flag is present. On each host, there must be on Erlang node + with the erl_boot_server which handles the load + requests. Hosts is a list of IP addresses (hostnames + are not acceptable).

+ + -id Id + +

Specifies the identity of the Erlang runtime system. If + the system runs as a distributed node, Id must be + identical to the name supplied with the -sname or + -name distribution flags.

+ + -setcookie Cookie + +

Specifies the cookie of the Erlang runtime system. This flag + is mandatory if the -loader inet flag is present.

+ + +
+ +
+ SEE ALSO +

init(3), + erl_boot_server(3)

+
+ + diff --git a/erts/doc/src/erl_set_memory_block.xml b/erts/doc/src/erl_set_memory_block.xml new file mode 100644 index 0000000000..d77da56d95 --- /dev/null +++ b/erts/doc/src/erl_set_memory_block.xml @@ -0,0 +1,172 @@ + + + + +
+ + 19982009 + Ericsson AB. 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. + + + + erl_set_memory_block + Patrik Nyblom + + + + + 98-08-05 + A + erl_set_memory_block.xml +
+ erl_set_memory_block + Custom memory allocation for Erlang on VxWorks® + +

This documentation is specific to VxWorks.

+

The function/command initiates custom + memory allocation for the Erlang emulator. It has to be called + before the Erlang emulator is started and makes Erlang use one + single large memory block for all memory allocation.

+

The memory within the block can be utilized by other tasks than + Erlang. This is accomplished by calling the functions + , and instead + of , and respectively.

+

The purpose of this is to avoid problems inherent in the + VxWorks systems library. The memory allocation within the + large memory block avoids fragmentation by using an "address + order first fit" algorithm. Another advantage of using a + separate memory block is that resource reclamation can be made + more easily when Erlang is stopped.

+

The function is callable from any C + program as an ordinary 10 argument function as well as + from the commandline.

+ + + + interl_set_memory_block(size_t size, void *ptr, int warn_mixed_malloc, int realloc_always_moves, int use_reclaim, ...) + Specify parameters for Erlang internal memory allocation. + +

The function is called before Erlang is + started to specify a large memory block where Erlang can + maintain memory internally.

+

Parameters:

+ + size_t size + The size in bytes of Erlang's internal memory block. Has to + be specified. Note that the VxWorks system uses dynamic + memory allocation heavily, so leave some memory to the system. + void *ptr + +

A pointer to the actual memory block of size + . If this is specified as 0 (NULL), Erlang will + allocate the memory when starting and will reclaim the + memory block (as a whole) when stopped.

+

If a memory block is allocated and provided here, the + etc routines can still be used after + the Erlang emulator is stopped. The Erlang emulator can + also be restarted while other tasks using the memory + block are running without destroying the memory. If + Erlang is to be restarted, also set the + flag.

+

If 0 is specified here, the Erlang system should not + be stopped while some other task uses the memory block + (has called ).

+ + int warn_mixed_malloc + +

If this flag is set to true (anything else than 0), the + system will write a warning message on the console if a + program is mixing normal with + or .

+ + int realloc_always_moves + +

If this flag is set to true (anything else than 0), all + calls to result in a moved memory + block. This can in certain conditions give less + fragmentation. This flag may be removed in future releases.

+ + int use_reclaim + +

If this flag is set to true (anything else than 0), all + memory allocated with is automatically + reclaimed as soon as a task exits. This is very useful + to make writing port programs (and other programs as + well) easier. Combine this with using the routines + etc. specified in the reclaim.h + file delivered in the Erlang distribution.

+ + +

Return Value:

+

Returns 0 (OK) on success, otherwise a value <> 0.

+ + + + interl_memory_show(...) + A utility similar to VxWorks , but for the Erlang memory area. + +

Return Value:

+

Returns 0 (OK) on success, otherwise a value <> 0.

+ + + + interl_mem_info_get(MEM_PART_STATS *stats) + A utility similar to VxWorks , but for the Erlang memory area. + +

Parameter:

+ + MEM_PART_STATS *stats + A pointer to a MEM_PART_STATS structure as defined in + ]]>. A successful call will fill in all + fields of the structure, on error all fields are left untouched. + +

Return Value:

+

Returns 0 (OK) on success, otherwise a value <> 0

+ + + + +
+ NOTES +

The memory block used by Erlang actually does not need to be + inside the area known to ordinary . It is possible + to set the preprocessor symbol when compiling + the wind kernel and then use user reserved memory for + Erlang. Erlang can therefor utilize memory above the 32 Mb limit + of VxWorks on the PowerPC architecture.

+

Example:

+

In config.h for the wind kernel:

+ +

In the start-up script/code for the VxWorks node:

+ +

Setting the flag decreases performance of the + system, but makes programming much easier. Other similar + facilities are present in the Erlang system even without using a + separate memory block. The routines called , + and provide the same + facilities by using VxWorks own . Similar routines + exist for files, see the file in the distribution.

+
+ + diff --git a/erts/doc/src/erlang.xml b/erts/doc/src/erlang.xml new file mode 100644 index 0000000000..fd4447009a --- /dev/null +++ b/erts/doc/src/erlang.xml @@ -0,0 +1,6920 @@ + + + + +
+ + 19962009 + Ericsson AB. 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. + + + + erlang + + + + + erlang.xml +
+ erlang + The Erlang BIFs + +

By convention, most built-in functions (BIFs) are seen as being + in the module erlang. A number of the BIFs are viewed more + or less as part of the Erlang programming language and are + auto-imported. Thus, it is not necessary to specify + the module name and both the calls atom_to_list(Erlang) and + erlang:atom_to_list(Erlang) are identical.

+

In the text, auto-imported BIFs are listed without module prefix. + BIFs listed with module prefix are not auto-imported.

+

BIFs may fail for a variety of reasons. All BIFs fail with + reason badarg if they are called with arguments of an + incorrect type. The other reasons that may make BIFs fail are + described in connection with the description of each individual + BIF.

+

Some BIFs may be used in guard tests, these are marked with + "Allowed in guard tests".

+ + +
+ DATA TYPES + + +ext_binary() + a binary data object, + structured according to the Erlang external term format + +iodata() = iolist() | binary() + +iolist() = [char() | binary() | iolist()] + a binary is allowed as the tail of the list +
+ + + abs(Number) -> int() | float() + Arithmetical absolute value + + Number = number() + + +

Returns an integer or float which is the arithmetical + absolute value of Number.

+ 
+> abs(-3.33).
+3.33
+> abs(-3).
+3
+

Allowed in guard tests.

+ + + + adler32(Data) -> int() + Compute adler32 checksum + + Data = iodata() + + +

Computes and returns the adler32 checksum for Data.

+ + + + adler32(OldAdler, Data) -> int() + Compute adler32 checksum + + OldAdler = int() + Data = iodata() + + +

Continue computing the adler32 checksum by combining + the previous checksum, OldAdler, with the checksum of + Data.

+

The following code:

+ + X = adler32(Data1), + Y = adler32(X,Data2). + +

- would assign the same value to Y as this would:

+ + Y = adler32([Data1,Data2]). + + + + + adler32_combine(FirstAdler, SecondAdler, SecondSize) -> int() + Combine two adler32 checksums + + FirstAdler = SecondAdler = int() + SecondSize = int() + + +

Combines two previously computed adler32 checksums. + This computation requires the size of the data object for + the second checksum to be known.

+

The following code:

+ + Y = adler32(Data1), + Z = adler32(Y,Data2). + +

- would assign the same value to Z as this would:

+ + X = adler32(Data1), + Y = adler32(Data2), + Z = adler32_combine(X,Y,iolist_size(Data2)). + + + + + erlang:append_element(Tuple1, Term) -> Tuple2 + Append an extra element to a tuple + + Tuple1 = Tuple2 = tuple() + Term = term() + + +

Returns a new tuple which has one element more than + Tuple1, and contains the elements in Tuple1 + followed by Term as the last element. Semantically + equivalent to + list_to_tuple(tuple_to_list(Tuple ++ [Term]), but much + faster.

+ 
+> erlang:append_element({one, two}, three).
+{one,two,three}
+ + + + apply(Fun, Args) -> term() | empty() + Apply a function to an argument list + + Fun = fun() + Args = [term()] + + +

Call a fun, passing the elements in Args as + arguments.

+

Note: If the number of elements in the arguments are known at + compile-time, the call is better written as + Fun(Arg1, Arg2, ... ArgN).

+ +

Earlier, Fun could also be given as + {Module, Function}, equivalent to + apply(Module, Function, Args). This usage is + deprecated and will stop working in a future release of + Erlang/OTP.

+ + + + + apply(Module, Function, Args) -> term() | empty() + Apply a function to an argument list + + Module = Function = atom() + Args = [term()] + + +

Returns the result of applying Function in + Module to Args. The applied function must + be exported from Module. The arity of the function is + the length of Args.

+ 
+> apply(lists, reverse, [[a, b, c]]).
+[c,b,a]
+

apply can be used to evaluate BIFs by using + the module name erlang.

+ 
+> apply(erlang, atom_to_list, ['Erlang']).
+"Erlang"
+

Note: If the number of arguments are known at compile-time, + the call is better written as + Module:Function(Arg1, Arg2, ..., ArgN).

+

Failure: error_handler:undefined_function/3 is called + if the applied function is not exported. The error handler + can be redefined (see + process_flag/2). + If the error_handler is undefined, or if the user has + redefined the default error_handler so the replacement + module is undefined, an error with the reason undef + is generated.

+ + + + atom_to_binary(Atom, Encoding) -> binary() + Return the binary representation of an atom + + Atom = atom() + Encoding = latin1 | utf8 | unicode + + +

Returns a binary which corresponds to the text + representation of Atom. If Encoding + is latin1, there will be one byte for each character + in the text representation. If Encoding is utf8 or + unicode, the characters will encoded using UTF-8 + (meaning that characters from 16#80 up to 0xFF will be + encode in two bytes).

+ +

Currently, atom_to_binary(Atom, latin1) can + never fail because the text representation of an atom can only contain + characters from 0 to 16#FF. In a future release, the text representation + of atoms might be allowed to contain any Unicode character + and atom_to_binary(Atom, latin1) will fail if the + text representation for the Atom contains a Unicode + character greater than 16#FF.

 + + 
+> atom_to_binary('Erlang', latin1).
+<<"Erlang">>
+ + + + atom_to_list(Atom) -> string() + Text representation of an atom + + Atom = atom() + + +

Returns a string which corresponds to the text + representation of Atom.

+ 
+> atom_to_list('Erlang').
+"Erlang"
+ + + + binary_to_atom(Binary, Encoding) -> atom() + Convert from text representation to an atom + + Binary = binary() + Encoding = latin1 | utf8 | unicode + + +

Returns the atom whose text representation is + Binary. If Encoding is latin1, no + translation of bytes in the binary is done. If Encoding + is utf8 or unicode, the binary must contain + valid UTF-8 sequences; furthermore, only Unicode characters up + to 0xFF are allowed.

+ +

binary_to_atom(Binary, utf8) will fail if + the binary contains Unicode characters greater than 16#FF. + In a future release, such Unicode characters might be allowed + and binary_to_atom(Binary, utf8) + will not fail in that case.

 + + 
+> binary_to_atom(<<"Erlang">>, latin1).
+'Erlang'
+> binary_to_atom(<<1024/utf8>>, utf8).
+** exception error: bad argument
+     in function  binary_to_atom/2
+        called as binary_to_atom(<<208,128>>,utf8)
+ + + + binary_to_existing_atom(Binary, Encoding) -> atom() + Convert from text representation to an atom + + Binary = binary() + Encoding = latin1 | utf8 | unicode + + +

Works like binary_to_atom/2, + but the atom must already exist.

+

Failure: badarg if the atom does not already exist.

+ + + + binary_to_list(Binary) -> [char()] + Convert a binary to a list + + Binary = binary() + + +

Returns a list of integers which correspond to the bytes of + Binary.

+ + + + binary_to_list(Binary, Start, Stop) -> [char()] + Convert part of a binary to a list + + Binary = binary() + Start = Stop = 1..byte_size(Binary) + + +

As binary_to_list/1, but returns a list of integers + corresponding to the bytes from position Start to + position Stop in Binary. Positions in the + binary are numbered starting from 1.

+ + + + bitstring_to_list(Bitstring) -> [char()|bitstring()] + Convert a bitstring to a list + + Bitstring = bitstring() + + +

Returns a list of integers which correspond to the bytes of + Bitstring. If the number of bits in the binary is not + divisible by 8, the last element of the list will be a bitstring + containing the remaining bits (1 up to 7 bits).

+ + + + binary_to_term(Binary) -> term() + Decode an Erlang external term format binary + + Binary = ext_binary() + + +

Returns an Erlang term which is the result of decoding + the binary object Binary, which must be encoded + according to the Erlang external term format. See also + term_to_binary/1.

+ + + + bit_size(Bitstring) -> int() + Return the size of a bitstring + + Bitstring = bitstring() + + +

Returns an integer which is the size in bits of Bitstring.

+ 
+> bit_size(<<433:16,3:3>>).
+19
+> bit_size(<<1,2,3>>).
+24
+

Allowed in guard tests.

+ + + + erlang:bump_reductions(Reductions) -> void() + Increment the reduction counter + + Reductions = int() + + +

This implementation-dependent function increments + the reduction counter for the calling process. In the Beam + emulator, the reduction counter is normally incremented by + one for each function and BIF call, and a context switch is + forced when the counter reaches the maximum number of reductions + for a process (2000 reductions in R12B).

+ +

This BIF might be removed in a future version of the Beam + machine without prior warning. It is unlikely to be + implemented in other Erlang implementations.

+ + + + + byte_size(Bitstring) -> int() + Return the size of a bitstring (or binary) + + Bitstring = bitstring() + + +

Returns an integer which is the number of bytes needed to contain + Bitstring. (That is, if the number of bits in Bitstring is not + divisible by 8, the resulting number of bytes will be rounded up.)

+ 
+> byte_size(<<433:16,3:3>>).
+3
+> byte_size(<<1,2,3>>).
+3
+

Allowed in guard tests.

+ + + + erlang:cancel_timer(TimerRef) -> Time | false + Cancel a timer + + TimerRef = ref() + Time = int() + + +

Cancels a timer, where TimerRef was returned by + either + erlang:send_after/3 + or + erlang:start_timer/3. + If the timer is there to be removed, the function returns + the time in milliseconds left until the timer would have expired, + otherwise false (which means that TimerRef was + never a timer, that it has already been cancelled, or that it + has already delivered its message).

+

See also + erlang:send_after/3, + erlang:start_timer/3, + and + erlang:read_timer/1.

+

Note: Cancelling a timer does not guarantee that the message + has not already been delivered to the message queue.

+ + + + + check_process_code(Pid, Module) -> bool() + Check if a process is executing old code for a module + + Pid = pid() + Module = atom() + + +

Returns true if the process Pid is executing + old code for Module. That is, if the current call of + the process executes old code for this module, or if the + process has references to old code for this module, or if the + process contains funs that references old code for this + module. Otherwise, it returns false.

+ 
+> check_process_code(Pid, lists).
+false
+

See also code(3).

+ + + + concat_binary(ListOfBinaries) + Concatenate a list of binaries (deprecated) + +

Do not use; use + list_to_binary/1 + instead.

+ + + + crc32(Data) -> int() + Compute crc32 (IEEE 802.3) checksum + + Data = iodata() + + +

Computes and returns the crc32 (IEEE 802.3 style) checksum for Data.

+ + + + crc32(OldCrc, Data) -> int() + Compute crc32 (IEEE 802.3) checksum + + OldCrc = int() + Data = iodata() + + +

Continue computing the crc32 checksum by combining + the previous checksum, OldCrc, with the checksum of + Data.

+

The following code:

+ + X = crc32(Data1), + Y = crc32(X,Data2). + +

- would assign the same value to Y as this would:

+ + Y = crc32([Data1,Data2]). + + + + + crc32_combine(FirstCrc, SecondCrc, SecondSize) -> int() + Combine two crc32 (IEEE 802.3) checksums + + FirstCrc = SecondCrc = int() + SecondSize = int() + + +

Combines two previously computed crc32 checksums. + This computation requires the size of the data object for + the second checksum to be known.

+

The following code:

+ + Y = crc32(Data1), + Z = crc32(Y,Data2). + +

- would assign the same value to Z as this would:

+ + X = crc32(Data1), + Y = crc32(Data2), + Z = crc32_combine(X,Y,iolist_size(Data2)). + + + + + date() -> {Year, Month, Day} + Current date + + Year = Month = Day = int() + + +

Returns the current date as {Year, Month, Day}.

+

The time zone and daylight saving time correction depend on + the underlying OS.

+ 
+> date().
+{1995,2,19}
+ + + + decode_packet(Type,Bin,Options) -> {ok,Packet,Rest} | {more,Length} | {error,Reason} + Extracts a protocol packet from a binary + + Bin = binary() + Options = [Opt] + Packet = binary() | HttpPacket + Rest = binary() + Length = int() | undefined + Reason = term() +  Type, Opt -- see below + + HttpPacket = HttpRequest | HttpResponse | HttpHeader | http_eoh | HttpError + HttpRequest = {http_request, HttpMethod, HttpUri, HttpVersion} + HttpResponse = {http_response, HttpVersion, integer(), HttpString} + HttpHeader = {http_header, int(), HttpField, Reserved=term(), Value=HttpString} + HttpError = {http_error, HttpString} + HttpMethod = HttpMethodAtom | HttpString + HttpMethodAtom = 'OPTIONS' | 'GET' | 'HEAD' | 'POST' | 'PUT' | 'DELETE' | 'TRACE' + HttpUri = '*' | {absoluteURI, http|https, Host=HttpString, Port=int()|undefined, Path=HttpString} | + {scheme, Scheme=HttpString, HttpString} | {abs_path, HttpString} | HttpString + HttpVersion = {Major=int(), Minor=int()} + HttpString = string() | binary() + HttpField = HttpFieldAtom | HttpString + 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' + + + +

Decodes the binary Bin according to the packet + protocol specified by Type. Very similar to the packet + handling done by sockets with the option {packet,Type}.

+

If an entire packet is contained in Bin it is + returned together with the remainder of the binary as + {ok,Packet,Rest}.

+

If Bin does not contain the entire packet, + {more,Length} is returned. Length is either the + expected total size of the packet or undefined + if the expected packet size is not known. decode_packet + can then be called again with more data added.

+

If the packet does not conform to the protocol format + {error,Reason} is returned.

+

The following values of Type are valid:

+ + raw | 0 + +

No packet handling is done. Entire binary is + returned unless it is empty.

+ + 1 | 2 | 4 + +

Packets consist of a header specifying the number of + bytes in the packet, followed by that number of bytes. + The length of header can be one, two, or four bytes; + the order of the bytes is big-endian. The header + will be stripped off when the packet is returned.

+ + line + +

A packet is a line terminated with newline. The + newline character is included in the returned packet + unless the line was truncated according to the option + line_length.

+ + asn1 | cdr | sunrm | fcgi | tpkt + +

The header is not stripped off.

+

The meanings of the packet types are as follows:

+ + asn1 - ASN.1 BER + sunrm - Sun's RPC encoding + cdr - CORBA (GIOP 1.1) + fcgi - Fast CGI + tpkt - TPKT format [RFC1006] + + + http | httph | http_bin | httph_bin + +

The Hypertext Transfer Protocol. The packets + are returned with the format according to + HttpPacket described above. A packet is either a + request, a response, a header or an end of header + mark. Invalid lines are returned as HttpError.

+

Recognized request methods and header fields are returned as atoms. + Others are returned as strings.

+

The protocol type http should only be used for + the first line when a HttpRequest or a + HttpResponse is expected. The following calls + should use httph to get HttpHeader's until + http_eoh is returned that marks the end of the + headers and the beginning of any following message body.

+

The variants http_bin and httph_bin will return + strings (HttpString) as binaries instead of lists.

+ + +

The following options are available:

+ + {packet_size, int()} +

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.

+ + {line_length, int()} +

Applies only to line oriented protocols + (line, http). Lines longer than this + will be truncated.

+ + + 
+> erlang:decode_packet(1,<<3,"abcd">>,[]).
+{ok,<<"abc">>,<<"d">>}
+> erlang:decode_packet(1,<<5,"abcd">>,[]).
+{more,6}
+ + + + delete_module(Module) -> true | undefined + Make the current code for a module old + + Module = atom() + + +

Makes the current code for Module become old code, and + deletes all references for this module from the export table. + Returns undefined if the module does not exist, + otherwise true.

+ +

This BIF is intended for the code server (see + code(3)) and should not be + used elsewhere.

+ +

Failure: badarg if there is already an old version of + Module.

+ + + + erlang:demonitor(MonitorRef) -> true + Stop monitoring + + MonitorRef = ref() + + +

If MonitorRef is a reference which the calling process + obtained by calling + erlang:monitor/2, + this monitoring is turned off. If the monitoring is already + turned off, nothing happens.

+

Once erlang:demonitor(MonitorRef) has returned it is + guaranteed that no {'DOWN', MonitorRef, _, _, _} message + due to the monitor will be placed in the callers message queue + in the future. A {'DOWN', MonitorRef, _, _, _} message + might have been placed in the callers message queue prior to + the call, though. Therefore, in most cases, it is advisable + to remove such a 'DOWN' message from the message queue + after monitoring has been stopped. + erlang:demonitor(MonitorRef, [flush]) can be used instead of + erlang:demonitor(MonitorRef) if this cleanup is wanted.

+ +

Prior to OTP release R11B (erts version 5.5) erlang:demonitor/1 + 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 + you were guaranteed not to receive a DOWN message + due to the monitor.

+

Current behavior can be viewed as two combined operations: + asynchronously send a "demonitor signal" to the monitored entity + and ignore any future results of the monitor.

+ +

Failure: It is an error if MonitorRef refers to a + monitoring started by another process. Not all such cases are + cheap to check; if checking is cheap, the call fails with + badarg (for example if MonitorRef is a remote + reference).

+ + + + erlang:demonitor(MonitorRef, OptionList) -> true|false + Stop monitoring + + MonitorRef = ref() + OptionList = [Option] + Option = flush + Option = info + + +

The returned value is true unless info is part + of OptionList. +

+

erlang:demonitor(MonitorRef, []) is equivalent to + erlang:demonitor(MonitorRef).

+

Currently the following Options are valid:

+ + flush + +

Remove (one) {_, MonitorRef, _, _, _} message, + if there is one, from the callers message queue after + monitoring has been stopped.

+

Calling erlang:demonitor(MonitorRef, [flush]) + is equivalent to the following, but more efficient:

+ + + erlang:demonitor(MonitorRef), + receive +\011{_, MonitorRef, _, _, _} -> +\011 true + after 0 -> +\011 true + end + + info + +

The returned value is one of the following:

+ + true +

The monitor was found and removed. In this case + no 'DOWN' message due to this monitor have + been nor will be placed in the message queue + of the caller. +

+ + false +

The monitor was not found and could not be removed. + This probably because someone already has placed a + 'DOWN' message corresponding to this monitor + in the callers message queue. +

+ + +

If the info option is combined with the flush + option, false will be returned if a flush was needed; + otherwise, true. +

+ + + +

More options may be added in the future.

+ +

Failure: badarg if OptionList is not a list, or + if Option is not a valid option, or the same failure as for + erlang:demonitor/1

+ + + + disconnect_node(Node) -> bool() | ignored + Force the disconnection of a node + + Node = atom() + + +

Forces the disconnection of a node. This will appear to + the node Node as if the local node has crashed. This + BIF is mainly used in the Erlang network authentication + protocols. Returns true if disconnection succeeds, + otherwise false. If the local node is not alive, + the function returns ignored.

+ + + + erlang:display(Term) -> true + Print a term on standard output + + Term = term() + + +

Prints a text representation of Term on the standard + output.

+ +

This BIF is intended for debugging only.

+ + + + + element(N, Tuple) -> term() + Get Nth element of a tuple + + N = 1..tuple_size(Tuple) + Tuple = tuple() + + +

Returns the Nth element (numbering from 1) of + Tuple.

+ 
+> element(2, {a, b, c}).
+b
+

Allowed in guard tests.

+ + + + erase() -> [{Key, Val}] + Return and delete the process dictionary + + Key = Val = term() + + +

Returns the process dictionary and deletes it.

+ 
+> put(key1, {1, 2, 3}),
+put(key2, [a, b, c]),
+erase().
+[{key1,{1,2,3}},{key2,[a,b,c]}]
+ + + + erase(Key) -> Val | undefined + Return and delete a value from the process dictionary + + Key = Val = term() + + +

Returns the value Val associated with Key and + deletes it from the process dictionary. Returns + undefined if no value is associated with Key.

+ 
+> put(key1, {merry, lambs, are, playing}),
+X = erase(key1),
+{X, erase(key1)}.
+{{merry,lambs,are,playing},undefined}
+ + + + erlang:error(Reason) + Stop execution with a given reason + + Reason = term() + + +

Stops the execution of the calling process with the reason + Reason, where Reason is any term. The actual + exit reason will be {Reason, Where}, where Where + is a list of the functions most recently called (the current + function first). Since evaluating this function causes + the process to terminate, it has no return value.

+ 
+> catch erlang:error(foobar).
+{'EXIT',{foobar,[{erl_eval,do_apply,5},
+                 {erl_eval,expr,5},
+                 {shell,exprs,6},
+                 {shell,eval_exprs,6},
+                 {shell,eval_loop,3}]}}
+ + + + erlang:error(Reason, Args) + Stop execution with a given reason + + Reason = term() + Args = [term()] + + +

Stops the execution of the calling process with the reason + Reason, where Reason is any term. The actual + exit reason will be {Reason, Where}, where Where + is a list of the functions most recently called (the current + function first). Args is expected to be the list of + arguments for the current function; in Beam it will be used + to provide the actual arguments for the current function in + the Where term. Since evaluating this function causes + the process to terminate, it has no return value.

+ + + + exit(Reason) + Stop execution with a given reason + + Reason = term() + + +

Stops the execution of the calling process with the exit + reason Reason, where Reason is any term. Since + evaluating this function causes the process to terminate, it + has no return value.

+ 
+> exit(foobar).
+** exception exit: foobar
+> catch exit(foobar).
+{'EXIT',foobar}
+ + + + exit(Pid, Reason) -> true + Send an exit signal to a process + + Pid = pid() + Reason = term() + + +

Sends an exit signal with exit reason Reason to + the process Pid.

+

The following behavior apply if Reason is any term + except normal or kill:

+

If Pid is not trapping exits, Pid itself will + exit with exit reason Reason. If Pid is trapping + exits, the exit signal is transformed into a message + {'EXIT', From, Reason} and delivered to the message + queue of Pid. From is the pid of the process + which sent the exit signal. See also + process_flag/2.

+

If Reason is the atom normal, Pid will + not exit. If it is trapping exits, the exit signal is + transformed into a message {'EXIT', From, normal} + and delivered to its message queue.

+

If Reason is the atom kill, that is if + exit(Pid, kill) is called, an untrappable exit signal + is sent to Pid which will unconditionally exit with + exit reason killed.

+ + + + float(Number) -> float() + Convert a number to a float + + Number = number() + + +

Returns a float by converting Number to a float.

+ 
+> float(55).
+55.0
+

Allowed in guard tests.

+ +

Note that if used on the top-level in a guard, it will + test whether the argument is a floating point number; for + clarity, use + is_float/1 instead.

+

When float/1 is used in an expression in a guard, + such as 'float(A) == 4.0', it converts a number as + described above.

+ + + + + float_to_list(Float) -> string() + Text representation of a float + + Float = float() + + +

Returns a string which corresponds to the text + representation of Float.

+ 
+> float_to_list(7.0).
+"7.00000000000000000000e+00"
+ + + + erlang:fun_info(Fun) -> [{Item, Info}] + Information about a fun + + Fun = fun() + Item, Info -- see below + + +

Returns a list containing information about the fun + Fun. 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.

+ +

This BIF is mainly intended for debugging, but it can + occasionally be useful in library functions that might need + to verify, for instance, the arity of a fun.

+ +

There are two types of funs with slightly different + semantics:

+

A fun created by fun M:F/A is called an + external fun. Calling it will always call the + function F with arity A in the latest code for + module M. Note that module M does not even need + to be loaded when the fun fun M:F/A is created.

+

All other funs are called local. When a local fun + is called, the same version of the code that created the fun + will be called (even if newer version of the module has been + loaded).

+

The following elements will always be present in the list + for both local and external funs:

+ + {type, Type} + +

Type is either local or external.

+ + {module, Module} + +

Module (an atom) is the module name.

+

If Fun is a local fun, Module is the module + in which the fun is defined.

+

If Fun is an external fun, Module is the + module that the fun refers to.

+ + {name, Name} + +

Name (an atom) is a function name.

+

If Fun is a local fun, Name is the name + of the local function that implements the fun. + (This name was generated by the compiler, and is generally + only of informational use. As it is a local function, it + is not possible to call it directly.) + If no code is currently loaded for the fun, [] + will be returned instead of an atom.

+

If Fun is an external fun, Name is the name + of the exported function that the fun refers to.

+ + {arity, Arity} + +

Arity is the number of arguments that the fun + should be called with.

+ + {env, Env} + +

Env (a list) is the environment or free variables + for the fun. (For external funs, the returned list is + always empty.)

+ + +

The following elements will only be present in the list if + Fun is local:

+ + {pid, Pid} + +

Pid is the pid of the process that originally + created the fun.

+ + {index, Index} + +

Index (an integer) is an index into the module's + fun table.

+ + {new_index, Index} + +

Index (an integer) is an index into the module's + fun table.

+ + {new_uniq, Uniq} + +

Uniq (a binary) is a unique value for this fun.

+ + {uniq, Uniq} + +

Uniq (an integer) is a unique value for this fun.

+ + + + + + erlang:fun_info(Fun, Item) -> {Item, Info} + Information about a fun + + Fun = fun() + Item, Info -- see below + + +

Returns information about Fun as specified by + Item, in the form {Item,Info}.

+

For any fun, Item can be any of the atoms + module, name, arity, or env.

+

For a local fun, Item can also be any of the atoms + index, new_index, new_uniq, + uniq, and pid. For an external fun, the value + of any of these items is always the atom undefined.

+

See + erlang:fun_info/1.

+ + + + erlang:fun_to_list(Fun) -> string() + Text representation of a fun + + Fun = fun() + + +

Returns a string which corresponds to the text + representation of Fun.

+ + + + erlang:function_exported(Module, Function, Arity) -> bool() + Check if a function is exported and loaded + + Module = Function = atom() + Arity = int() + + +

Returns true if the module Module is loaded + and contains an exported function Function/Arity; + otherwise false.

+

Returns false for any BIF (functions implemented in C + rather than in Erlang).

+ + + + garbage_collect() -> true + Force an immediate garbage collection of the calling process + +

Forces an immediate garbage collection of the currently + executing process. The function should not be used, unless + it has been noticed -- or there are good reasons to suspect -- + that the spontaneous garbage collection will occur too late + or not at all. Improper use may seriously degrade system + performance.

+

Compatibility note: In versions of OTP prior to R7, + the garbage collection took place at the next context switch, + not immediately. To force a context switch after a call to + erlang:garbage_collect(), it was sufficient to make + any function call.

+ + + + garbage_collect(Pid) -> bool() + Force an immediate garbage collection of a process + + Pid = pid() + + +

Works like erlang:garbage_collect() but on any + process. The same caveats apply. Returns false if + Pid refers to a dead process; true otherwise.

+ + + + get() -> [{Key, Val}] + Return the process dictionary + + Key = Val = term() + + +

Returns the process dictionary as a list of + {Key, Val} tuples.

+ 
+> put(key1, merry),
+put(key2, lambs),
+put(key3, {are, playing}),
+get().
+[{key1,merry},{key2,lambs},{key3,{are,playing}}]
+ + + + get(Key) -> Val | undefined + Return a value from the process dictionary + + Key = Val = term() + + +

Returns the value Valassociated with Key in + the process dictionary, or undefined if Key + does not exist.

+ 
+> put(key1, merry),
+put(key2, lambs),
+put({any, [valid, term]}, {are, playing}),
+get({any, [valid, term]}).
+{are,playing}
+ + + + erlang:get_cookie() -> Cookie | nocookie + Get the magic cookie of the local node + + Cookie = atom() + + +

Returns the magic cookie of the local node, if the node is + alive; otherwise the atom nocookie.

+ + + + get_keys(Val) -> [Key] + Return a list of keys from the process dictionary + + Val = Key = term() + + +

Returns a list of keys which are associated with the value + Val in the process dictionary.

+ 
+> put(mary, {1, 2}),
+put(had, {1, 2}),
+put(a, {1, 2}),
+put(little, {1, 2}),
+put(dog, {1, 3}),
+put(lamb, {1, 2}),
+get_keys({1, 2}).
+[mary,had,a,little,lamb]
+ + + + erlang:get_stacktrace() -> [{Module, Function, Arity | Args}] + Get the call stack back-trace of the last exception + + Module = Function = atom() + Arity = int() + Args = [term()] + + +

Get the call stack back-trace (stacktrace) of the last + exception in the calling process as a list of + {Module,Function,Arity} tuples. + The Arity field in the first tuple may be the argument + list of that function call instead of an arity integer, + depending on the exception.

+

If there has not been any exceptions in a process, the + stacktrace is []. After a code change for the process, + the stacktrace may also be reset to [].

+

The stacktrace is the same data as the catch operator + returns, for example:

+

{'EXIT',{badarg,Stacktrace}} = catch abs(x)

+

See also + erlang:error/1 and + erlang:error/2.

+ + + + group_leader() -> GroupLeader + Get the group leader for the calling process + + GroupLeader = pid() + + +

Returns the pid of the group leader for the process which + evaluates the function.

+

Every process is a member of some process group and all + groups have a group leader. All IO from the group + is channeled to the group leader. When a new process is + spawned, it gets the same group leader as the spawning + process. Initially, at system start-up, init is both + its own group leader and the group leader of all processes.

+ + + + group_leader(GroupLeader, Pid) -> true + Set the group leader for a process + + GroupLeader = Pid = pid() + + +

Sets the group leader of Pid to GroupLeader. + Typically, this is used when a processes started from a + certain shell should have another group leader than + init.

+

See also + group_leader/0.

+ + + + halt() + Halt the Erlang runtime system and indicate normal exit to the calling environment + +

Halts the Erlang runtime system and indicates normal exit to + the calling environment. Has no return value.

+ 
+> halt().
+os_prompt%
+ + + + halt(Status) + Halt the Erlang runtime system + + Status = int()>=0 | string() + + +

Status must be a non-negative integer, or a string. + Halts the Erlang runtime system. Has no return value. + If Status is an integer, it is returned as an exit + status of Erlang to the calling environment. + If Status is a string, produces an Erlang crash dump + with String as slogan, and then exits with a non-zero + status code.

+

Note that on many platforms, only the status codes 0-255 are + supported by the operating system.

+ + + + erlang:hash(Term, Range) -> Hash + Hash function (deprecated) + +

Returns a hash value for Term within the range + 1..Range. The allowed range is 1..2^27-1.

+ +

This BIF is deprecated as the hash value may differ on + different architectures. Also the hash values for integer + terms larger than 2^27 as well as large binaries are very + poor. The BIF is retained for backward compatibility + reasons (it may have been used to hash records into a file), + but all new code should use one of the BIFs + erlang:phash/2 or erlang:phash2/1,2 instead.

+ + + + + hd(List) -> term() + Head of a list + + List = [term()] + + +

Returns the head of List, that is, the first element.

+ 
+> hd([1,2,3,4,5]).
+1
+

Allowed in guard tests.

+

Failure: badarg if List is the empty list [].

+ + + + erlang:hibernate(Module, Function, Args) + Hibernate a process until a message is sent to it + + Module = Function = atom() + Args = [term()] + + +

Puts the calling process into a wait state where its memory + allocation has been reduced as much as possible, which is + useful if the process does not expect to receive any messages + in the near future.

+

The process will be awaken when a message is sent to it, and + control will resume in Module:Function with + the arguments given by Args with the call stack + emptied, meaning that the process will terminate when that + function returns. Thus erlang:hibernate/3 will never + return to its caller.

+

If the process has any message in its message queue, + the process will be awaken immediately in the same way as + described above.

+

In more technical terms, what erlang:hibernate/3 does + is the following. It discards the call stack for the process. + Then it garbage collects the process. After the garbage + collection, all live data is in one continuous heap. The heap + is then shrunken to the exact same size as the live data + which it holds (even if that size is less than the minimum + heap size for the process).

+

If the size of the live data in the process is less than + the minimum heap size, the first garbage collection occurring + after the process has been awaken will ensure that the heap + size is changed to a size not smaller than the minimum heap + size.

+

Note that emptying the call stack means that any surrounding + catch is removed and has to be re-inserted after + hibernation. One effect of this is that processes started + using proc_lib (also indirectly, such as + gen_server processes), should use + proc_lib:hibernate/3 + instead to ensure that the exception handler continues to work + when the process wakes up.

+ + + + integer_to_list(Integer) -> string() + Text representation of an integer + + Integer = int() + + +

Returns a string which corresponds to the text + representation of Integer.

+ 
+> integer_to_list(77).
+"77"
+ + + + erlang:integer_to_list(Integer, Base) -> string() + Text representation of an integer + + Integer = int() + Base = 2..36 + + +

Returns a string which corresponds to the text + representation of Integer in base Base.

+ 
+> erlang:integer_to_list(1023, 16).
+"3FF"
+ + + + iolist_to_binary(IoListOrBinary) -> binary() + Convert an iolist to a binary + + IoListOrBinary = iolist() | binary() + + +

Returns a binary which is made from the integers and + binaries in IoListOrBinary.

+ 
+> Bin1 = <<1,2,3>>.
+<<1,2,3>>
+> Bin2 = <<4,5>>.
+<<4,5>>
+> Bin3 = <<6>>.
+<<6>>
+> iolist_to_binary([Bin1,1,[2,3,Bin2],4|Bin3]).
+<<1,2,3,1,2,3,4,5,4,6>>
+ + + + iolist_size(Item) -> int() + Size of an iolist + + Item = iolist() | binary() + + +

Returns an integer which is the size in bytes + of the binary that would be the result of + iolist_to_binary(Item).

+ 
+> iolist_size([1,2|<<3,4>>]).
+4
+ + + + is_alive() -> bool() + Check whether the local node is alive + +

Returns true if the local node is alive; that is, if + the node can be part of a distributed system. Otherwise, it + returns false.

+ + + + is_atom(Term) -> bool() + Check whether a term is an atom + + Term = term() + + +

Returns true if Term is an atom; + otherwise returns false.

+

Allowed in guard tests.

+ + + + is_binary(Term) -> bool() + Check whether a term is a binary + + Term = term() + + +

Returns true if Term is a binary; + otherwise returns false.

+ +

A binary always contains a complete number of bytes.

+ +

Allowed in guard tests.

+ + + + is_bitstring(Term) -> bool() + Check whether a term is a bitstring + + Term = term() + + +

Returns true if Term is a bitstring (including a binary); + otherwise returns false.

+ +

Allowed in guard tests.

+ + + + is_boolean(Term) -> bool() + Check whether a term is a boolean + + Term = term() + + +

Returns true if Term is + either the atom true or the atom false + (i.e. a boolean); otherwise returns false.

+

Allowed in guard tests.

+ + + + erlang:is_builtin(Module, Function, Arity) -> bool() + Check if a function is a BIF implemented in C + + Module = Function = atom() + Arity = int() + + +

Returns true if Module:Function/Arity is + a BIF implemented in C; otherwise returns false. + This BIF is useful for builders of cross reference tools.

+ + + + is_float(Term) -> bool() + Check whether a term is a float + + Term = term() + + +

Returns true if Term is a floating point + number; otherwise returns false.

+

Allowed in guard tests.

+ + + + is_function(Term) -> bool() + Check whether a term is a fun + + Term = term() + + +

Returns true if Term is a fun; otherwise + returns false.

+

Allowed in guard tests.

+ + + + is_function(Term, Arity) -> bool() + Check whether a term is a fun with a given arity + + Term = term() + Arity = int() + + +

Returns true if Term is a fun that can be + applied with Arity number of arguments; otherwise + returns false.

+

Allowed in guard tests.

+ +

Currently, is_function/2 will also return + true if the first argument is a tuple fun (a tuple + containing two atoms). In a future release, tuple funs will + no longer be supported and is_function/2 will return + false if given a tuple fun.

+ + + + + is_integer(Term) -> bool() + Check whether a term is an integer + + Term = term() + + +

Returns true if Term is an integer; + otherwise returns false.

+

Allowed in guard tests.

+ + + + is_list(Term) -> bool() + Check whether a term is a list + + Term = term() + + +

Returns true if Term is a list with + zero or more elements; otherwise returns false.

+

Allowed in guard tests.

+ + + + is_number(Term) -> bool() + Check whether a term is a number + + Term = term() + + +

Returns true if Term is either an integer or a + floating point number; otherwise returns false.

+

Allowed in guard tests.

+ + + + is_pid(Term) -> bool() + Check whether a term is a pid + + Term = term() + + +

Returns true if Term is a pid (process + identifier); otherwise returns false.

+

Allowed in guard tests.

+ + + + is_port(Term) -> bool() + Check whether a term is a port + + Term = term() + + +

Returns true if Term is a port identifier; + otherwise returns false.

+

Allowed in guard tests.

+ + + + is_process_alive(Pid) -> bool() + Check whether a process is alive + + Pid = pid() + + +

+ Pid must refer to a process at the local node. + Returns true if the process exists and is alive, that + is, is not exiting and has not exited. Otherwise, returns + false. +

+ + + + is_record(Term, RecordTag) -> bool() + Check whether a term appears to be a record + + Term = term() + RecordTag = atom() + + +

Returns true if Term is a tuple and its first + element is RecordTag. Otherwise, returns false.

+ +

Normally the compiler treats calls to is_record/2 + specially. It emits code to verify that Term is a + tuple, that its first element is RecordTag, and that + the size is correct. However, if the RecordTag is + not a literal atom, the is_record/2 BIF will be + called instead and the size of the tuple will not be + verified.

+ +

Allowed in guard tests, if RecordTag is a literal + atom.

+ + + + is_record(Term, RecordTag, Size) -> bool() + Check whether a term appears to be a record + + Term = term() + RecordTag = atom() + Size = int() + + +

RecordTag must be an atom. Returns true if + Term is a tuple, its first element is RecordTag, + and its size is Size. Otherwise, returns false.

+

Allowed in guard tests, provided that RecordTag is + a literal atom and Size is a literal integer.

+ +

This BIF is documented for completeness. In most cases + is_record/2 should be used.

+ + + + + is_reference(Term) -> bool() + Check whether a term is a reference + + Term = term() + + +

Returns true if Term is a reference; + otherwise returns false.

+

Allowed in guard tests.

+ + + + is_tuple(Term) -> bool() + Check whether a term is a tuple + + Term = term() + + +

Returns true if Term is a tuple; + otherwise returns false.

+

Allowed in guard tests.

+ + + + length(List) -> int() + Length of a list + + List = [term()] + + +

Returns the length of List.

+ 
+> length([1,2,3,4,5,6,7,8,9]).
+9
+

Allowed in guard tests.

+ + + + link(Pid) -> true + Create a link to another process (or port) + + Pid = pid() | port() + + +

Creates a link between the calling process and another + process (or port) Pid, if there is not such a link + already. If a process attempts to create a link to itself, + nothing is done. Returns true.

+

If Pid does not exist, the behavior of the BIF depends + on if the calling process is trapping exits or not (see + process_flag/2):

+ + If the calling process is not trapping exits, and + checking Pid is cheap -- that is, if Pid is + local -- link/1 fails with reason noproc. + Otherwise, if the calling process is trapping exits, + and/or Pid is remote, link/1 returns + true, but an exit signal with reason noproc + is sent to the calling process. + + + + + list_to_atom(String) -> atom() + Convert from text representation to an atom + + String = string() + + +

Returns the atom whose text representation is String.

+ 
+> list_to_atom("Erlang").
+'Erlang'
+ + + + list_to_binary(IoList) -> binary() + Convert a list to a binary + + IoList = iolist() + + +

Returns a binary which is made from the integers and + binaries in IoList.

+ 
+> Bin1 = <<1,2,3>>.
+<<1,2,3>>
+> Bin2 = <<4,5>>.
+<<4,5>>
+> Bin3 = <<6>>.
+<<6>>
+> list_to_binary([Bin1,1,[2,3,Bin2],4|Bin3]).
+<<1,2,3,1,2,3,4,5,4,6>>
+ + + + list_to_bitstring(BitstringList) -> bitstring() + Convert a list to a bitstring + + BitstringList = [BitstringList | bitstring() | char()] + + +

Returns a bitstring which is made from the integers and + bitstrings in BitstringList. (The last tail in BitstringList + is allowed to be a bitstring.)

+ 
+> Bin1 = <<1,2,3>>.
+<<1,2,3>>
+> Bin2 = <<4,5>>.
+<<4,5>>
+> Bin3 = <<6,7:4,>>.
+<<6>>
+> list_to_binary([Bin1,1,[2,3,Bin2],4|Bin3]).
+<<1,2,3,1,2,3,4,5,4,6,7:46>>
+ + + + list_to_existing_atom(String) -> atom() + Convert from text representation to an atom + + String = string() + + +

Returns the atom whose text representation is String, + but only if there already exists such atom.

+

Failure: badarg if there does not already exist an atom + whose text representation is String.

+ + + + list_to_float(String) -> float() + Convert from text representation to a float + + String = string() + + +

Returns the float whose text representation is String.

+ 
+> list_to_float("2.2017764e+0").
+2.2017764
+

Failure: badarg if String contains a bad + representation of a float.

+ + + + list_to_integer(String) -> int() + Convert from text representation to an integer + + String = string() + + +

Returns an integer whose text representation is + String.

+ 
+> list_to_integer("123").
+123
+

Failure: badarg if String contains a bad + representation of an integer.

+ + + + erlang:list_to_integer(String, Base) -> int() + Convert from text representation to an integer + + String = string() + Base = 2..36 + + +

Returns an integer whose text representation in base + Base is String.

+ 
+> erlang:list_to_integer("3FF", 16).
+1023
+

Failure: badarg if String contains a bad + representation of an integer.

+ + + + list_to_pid(String) -> pid() + Convert from text representation to a pid + + String = string() + + +

Returns a pid whose text representation is String.

+ +

This BIF is intended for debugging and for use in + the Erlang operating system. It should not be used in + application programs.

+ + 
+> list_to_pid("<0.4.1>").
+<0.4.1>
+

Failure: badarg if String contains a bad + representation of a pid.

+ + + + list_to_tuple(List) -> tuple() + Convert a list to a tuple + + List = [term()] + + +

Returns a tuple which corresponds to List. List + can contain any Erlang terms.

+ 
+> list_to_tuple([share, ['Ericsson_B', 163]]).
+{share, ['Ericsson_B', 163]}
+ + + + load_module(Module, Binary) -> {module, Module} | {error, Reason} + Load object code for a module + + Module = atom() + Binary = binary() + Reason = badfile | not_purged | badfile + + +

If Binary contains the object code for the module + Module, this BIF loads that object code. Also, if + the code for the module Module already exists, all + export references are replaced so they point to the newly + loaded code. The previously loaded code is kept in the system + as old code, as there may still be processes which are + executing that code. It returns either + {module, Module}, or {error, Reason} if loading + fails. Reason is one of the following:

+ + badfile + +

The object code in Binary has an incorrect format.

+ + not_purged + +

Binary contains a module which cannot be loaded + because old code for this module already exists.

+ + badfile + +

The object code contains code for another module than + Module

+ + + +

This BIF is intended for the code server (see + code(3)) and should not be + used elsewhere.

+ + + + + erlang:load_nif(Path, LoadInfo) -> ok | {error, Reason, Text} + Load NIF library + + Path = string() + LoadInfo = term() + Reason = load_failed | bad_lib | load | reload | + upgrade | old_code + Text = string() + + + +

This BIF is currently introduced as an experimental + feature. The interface may be changed in any way in future + releases.

+ +

Loads and links a dynamic library containing native + implemented functions (NIFs) for a module. Path is a + file path to the sharable object/dynamic library file minus + the OS-dependant file extension (.so for Unix and .ddl for + Windows). See erl_nif + on how to implement a NIF library.

+

LoadInfo can be any term. It will be passed on to + the library as part of the initialization. A good practice is + to include a module version number to support future code + upgrade scenarios.

+

The call to load_nif/2 must be made + directly from the Erlang code of the module that the + NIF library belongs to.

+

It returns either ok, or {error,Reason,Text} + if loading fails. Reason is one of the atoms below, + while Text is a human readable string that may give + some more information about the failure:

+ + load_failed + +

The OS failed to load the NIF library.

+ + bad_lib + +

The library did not fulfil the requirements as a NIF + library of the calling module.

+ + load | reload | upgrade + +

The corresponding library callback was not successful.

+ + old_code + +

The call to load_nif/2 was made from the old + code of a module that has been upgraded. This is not + allowed.

+ + + + + + erlang:loaded() -> [Module] + List of all loaded modules + + Module = atom() + + +

Returns a list of all loaded Erlang modules (current and/or + old code), including preloaded modules.

+

See also code(3).

+ + + + erlang:localtime() -> {Date, Time} + Current local date and time + + Date = {Year, Month, Day} + Time = {Hour, Minute, Second} +  Year = Month = Day = Hour = Minute = Second = int() + + +

Returns the current local date and time + {{Year, Month, Day}, {Hour, Minute, Second}}.

+

The time zone and daylight saving time correction depend + on the underlying OS.

+ 
+> erlang:localtime().
+{{1996,11,6},{14,45,17}}
+ + + + erlang:localtime_to_universaltime({Date1, Time1}) -> {Date2, Time2} + Convert from local to Universal Time Coordinated (UTC) date and time + + Date1 = Date2 = {Year, Month, Day} + Time1 = Time2 = {Hour, Minute, Second} +  Year = Month = Day = Hour = Minute = Second = int() + + +

Converts local date and time to Universal Time Coordinated + (UTC), if this is supported by the underlying OS. Otherwise, + no conversion is done and {Date1, Time1} is returned.

+ 
+> erlang:localtime_to_universaltime({{1996,11,6},{14,45,17}}).
+{{1996,11,6},{13,45,17}}
+

Failure: badarg if Date1 or Time1 do + not denote a valid date or time.

+ + + + erlang:localtime_to_universaltime({Date1, Time1}, IsDst) -> {Date2, Time2} + Convert from local to Universal Time Coordinated (UTC) date and time + + Date1 = Date2 = {Year, Month, Day} + Time1 = Time2 = {Hour, Minute, Second} +  Year = Month = Day = Hour = Minute = Second = int() + IsDst = true | false | undefined + + +

Converts local date and time to Universal Time Coordinated + (UTC) just like erlang:localtime_to_universaltime/1, + but the caller decides if daylight saving time is active or + not.

+

If IsDst == true the {Date1, Time1} is during + daylight saving time, if IsDst == false it is not, + and if IsDst == undefined the underlying OS may + guess, which is the same as calling + erlang:localtime_to_universaltime({Date1, Time1}).

+ 
+> erlang:localtime_to_universaltime({{1996,11,6},{14,45,17}}, true).
+{{1996,11,6},{12,45,17}}
+> erlang:localtime_to_universaltime({{1996,11,6},{14,45,17}}, false).
+{{1996,11,6},{13,45,17}}
+> erlang:localtime_to_universaltime({{1996,11,6},{14,45,17}}, undefined).
+{{1996,11,6},{13,45,17}}
+

Failure: badarg if Date1 or Time1 do + not denote a valid date or time.

+ + + + make_ref() -> ref() + Return an almost unique reference + +

Returns an almost unique reference.

+

The returned reference will re-occur after approximately 2^82 + calls; therefore it is unique enough for practical purposes.

+ 
+> make_ref().
+#Ref<0.0.0.135>
+ + + + erlang:make_tuple(Arity, InitialValue) -> tuple() + Create a new tuple of a given arity + + Arity = int() + InitialValue = term() + + +

Returns a new tuple of the given Arity, where all + elements are InitialValue.

+ 
+> erlang:make_tuple(4, []).
+{[],[],[],[]}
+ + + + erlang:make_tuple(Arity, Default, InitList) -> tuple() + Create a new tuple with given arity and contents + + Arity = int() + Default = term() + InitList = [{Position,term()}] + Position = integer() + + +

erlang:make_tuple first creates a tuple of size Arity + where each element has the value Default. It then fills + in values from InitList. Each list element in InitList + must be a two-tuple where the first element is a position in the + newly created tuple and the second element is any term. If a position + occurs more than once in the list, the term corresponding to + last occurrence will be used.

+ 
+> erlang:make_tuple(5, [], [{2,ignored},{5,zz},{2,aa}]).
+{{[],aa,[],[],zz}
+ + + + erlang:max(Term1, Term2) -> Maximum + Return the largest of two term + + Term1 = Term2 = Maximum = term() + + +

Return the largest of Term1 and Term2; + if the terms compares equal, Term1 will be returned.

+ + + + erlang:md5(Data) -> Digest + Compute an MD5 message digest + + Data = iodata() + Digest = binary() + + +

Computes an MD5 message digest from Data, where + the length of the digest is 128 bits (16 bytes). Data + is a binary or a list of small integers and binaries.

+

See The MD5 Message Digest Algorithm (RFC 1321) for more + information about MD5.

+

The MD5 Message Digest Algorithm is not considered + safe for code-signing or software integrity purposes.

 + + + + erlang:md5_final(Context) -> Digest + Finish the update of an MD5 context and return the computed MD5 message digest + + Context = Digest = binary() + + +

Finishes the update of an MD5 Context and returns + the computed MD5 message digest.

+ + + + erlang:md5_init() -> Context + Create an MD5 context + + Context = binary() + + +

Creates an MD5 context, to be used in subsequent calls to + md5_update/2.

+ + + + erlang:md5_update(Context, Data) -> NewContext + Update an MD5 context with data, and return a new context + + Data = iodata() + Context = NewContext = binary() + + +

Updates an MD5 Context with Data, and returns + a NewContext.

+ + + + erlang:memory() -> [{Type, Size}] + Information about dynamically allocated memory + + Type, Size -- see below + + +

Returns a list containing information about memory + dynamically allocated by the Erlang emulator. Each element of + the list is a tuple {Type, Size}. The first element + Typeis an atom describing memory type. The second + element Sizeis memory size in bytes. A description of + each memory type follows:

+ + total + +

The total amount of memory currently allocated, which is + the same as the sum of memory size for processes + and system.

+ + processes + +

The total amount of memory currently allocated by + the Erlang processes.

+ + processes_used + +

The total amount of memory currently used by the Erlang + processes.

+

This memory is part of the memory presented as + processes memory.

+ + system + +

The total amount of memory currently allocated by + the emulator that is not directly related to any Erlang + process.

+

Memory presented as processes is not included in + this memory.

+ + atom + +

The total amount of memory currently allocated for atoms.

+

This memory is part of the memory presented as + system memory.

+ + atom_used + +

The total amount of memory currently used for atoms.

+

This memory is part of the memory presented as + atom memory.

+ + binary + +

The total amount of memory currently allocated for + binaries.

+

This memory is part of the memory presented as + system memory.

+ + code + +

The total amount of memory currently allocated for + Erlang code.

+

This memory is part of the memory presented as + system memory.

+ + ets + +

The total amount of memory currently allocated for ets + tables.

+

This memory is part of the memory presented as + system memory.

+ + maximum + +

The maximum total amount of memory allocated since + the emulator was started.

+

This tuple is only present when the emulator is run with + instrumentation.

+

For information on how to run the emulator with + instrumentation see + instrument(3) + and/or erl(1).

+ + + +

The system value is not complete. Some allocated + memory that should be part of the system value are + not.

+

When the emulator is run with instrumentation, + the system value is more accurate, but memory + directly allocated by malloc (and friends) are still + not part of the system value. Direct calls to + malloc are only done from OS specific runtime + libraries and perhaps from user implemented Erlang drivers + that do not use the memory allocation functions in + the driver interface.

+

Since the total value is the sum of processes + and system the error in system will propagate + to the total value.

+

The different amounts of memory that are summed are + not gathered atomically which also introduce + an error in the result.

+ +

The different values has the following relation to each + other. Values beginning with an uppercase letter is not part + of the result.

+ +\011total = processes + system +\011processes = processes_used + ProcessesNotUsed +\011system = atom + binary + code + ets + OtherSystem +\011atom = atom_used + AtomNotUsed + +\011RealTotal = processes + RealSystem +\011RealSystem = system + MissedSystem +

More tuples in the returned list may be added in the future.

+ +

The total value is supposed to be the total amount + of memory dynamically allocated by the emulator. Shared + libraries, the code of the emulator itself, and + the emulator stack(s) are not supposed to be included. That + is, the total value is not supposed to be + equal to the total size of all pages mapped to the emulator. + Furthermore, due to fragmentation and pre-reservation of + memory areas, the size of the memory segments which contain + the dynamically allocated memory blocks can be substantially + larger than the total size of the dynamically allocated + memory blocks.

+ + +

+ Since erts version 5.6.4 erlang:memory/0 requires that + all erts_alloc(3) + allocators are enabled (default behaviour). +

+ +

Failure:

+ + notsup + + If an erts_alloc(3) + allocator has been disabled. + + + + + + erlang:memory(Type | [Type]) -> Size | [{Type, Size}] + Information about dynamically allocated memory + + Type, Size -- see below + + +

Returns the memory size in bytes allocated for memory of + type Type. The argument can also be given as a list + of Type atoms, in which case a corresponding list of + {Type, Size} tuples is returned.

+ +

+ Since erts version 5.6.4 erlang:memory/1 requires that + all erts_alloc(3) + allocators are enabled (default behaviour). +

+ +

Failures:

+ + badarg + + If Type is not one of the memory types listed in the + documentation of + erlang:memory/0. + + badarg + + If maximum is passed as Type and the emulator + is not run in instrumented mode. + + notsup + + If an erts_alloc(3) + allocator has been disabled. + + +

See also + erlang:memory/0.

+ + + + erlang:min(Term1, Term2) -> Minimum + Return the smallest of two term + + Term1 = Term2 = Minimum = term() + + +

Return the smallest of Term1 and Term2; + if the terms compare equal, Term1 will be returned.

+ + + + module_loaded(Module) -> bool() + Check if a module is loaded + + Module = atom() + + +

Returns true if the module Module is loaded, + otherwise returns false. It does not attempt to load + the module.

+ +

This BIF is intended for the code server (see + code(3)) and should not be + used elsewhere.

+ + + + + erlang:monitor(Type, Item) -> MonitorRef + Start monitoring + + Type = process + Item = pid() | {RegName, Node} | RegName +  RegName = atom() +  Node = node() + MonitorRef = reference() + + +

The calling process starts monitoring Item which is + an object of type Type.

+

Currently only processes can be monitored, i.e. the only + allowed Type is process, but other types may be + allowed in the future.

+

Item can be:

+ + pid() + +

The pid of the process to monitor.

+ + {RegName, Node} + +

A tuple consisting of a registered name of a process and + a node name. The process residing on the node Node + with the registered name RegName will be monitored.

+ + RegName + +

The process locally registered as RegName will be + monitored.

+ + + +

When a process is monitored by registered name, the process + that has the registered name at the time when + erlang:monitor/2 is called will be monitored. + The monitor will not be effected, if the registered name is + unregistered.

+ +

A 'DOWN' message will be sent to the monitoring + process if Item dies, if Item does not exist, + or if the connection is lost to the node which Item + resides on. A 'DOWN' message has the following pattern:

+ +{'DOWN', MonitorRef, Type, Object, Info} +

where MonitorRef and Type are the same as + described above, and:

+ + Object + +

A reference to the monitored object:

+ + the pid of the monitored process, if Item was + specified as a pid. + {RegName, Node}, if Item was specified as + {RegName, Node}. + {RegName, Node}, if Item was specified as + RegName. Node will in this case be the + name of the local node (node()). + + + Info + +

Either the exit reason of the process, noproc + (non-existing process), or noconnection (no + connection to Node).

+ + + +

If/when erlang:monitor/2 is extended (e.g. to + handle other item types than process), other + possible values for Object, and Info in the + 'DOWN' message will be introduced.

+ +

The monitoring is turned off either when the 'DOWN' + message is sent, or when + erlang:demonitor/1 + is called.

+

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 badarg.

+

Making several calls to erlang:monitor/2 for the same + Item is not an error; it results in as many, completely + independent, monitorings.

+ +

The format of the 'DOWN' message changed in the 5.2 + version of the emulator (OTP release R9B) for monitor by registered name. The Object element of + the 'DOWN' message could in earlier versions + sometimes be the pid of the monitored process and sometimes + be the registered name. Now the Object element is + always a tuple consisting of the registered name and + the node name. Processes on new nodes (emulator version 5.2 + or greater) will always get 'DOWN' messages on + the new format even if they are monitoring processes on old + nodes. Processes on old nodes will always get 'DOWN' + messages on the old format.

+ + + + + monitor_node(Node, Flag) -> true + Monitor the status of a node + + Node = node() + Flag = bool() + + +

Monitors the status of the node Node. If Flag + is true, monitoring is turned on; if Flag is + false, monitoring is turned off.

+

Making several calls to monitor_node(Node, true) for + the same Node is not an error; it results in as many, + completely independent, monitorings.

+

If Node fails or does not exist, the message + {nodedown, Node} is delivered to the process. If a + process has made two calls to monitor_node(Node, true) + and Node terminates, two nodedown messages are + delivered to the process. If there is no connection to + Node, there will be an attempt to create one. If this + fails, a nodedown message is delivered.

+

Nodes connected through hidden connections can be monitored + as any other node.

+

Failure: badargif the local node is not alive.

+ + + + erlang:monitor_node(Node, Flag, Options) -> true + Monitor the status of a node + + Node = node() + Flag = bool() + Options = [Option] + Option = allow_passive_connect + + +

Behaves as monitor_node/2 except that it allows an + extra option to be given, namely allow_passive_connect. + The option allows the BIF to wait the normal net connection + timeout for the monitored node to connect itself, + even if it cannot be actively connected from this node + (i.e. it is blocked). The state where this might be useful can + only be achieved by using the kernel option + dist_auto_connect once. If that kernel option is not + used, the allow_passive_connect option has no + effect.

+ +

The allow_passive_connect option is used + internally and is seldom needed in applications where the + network topology and the kernel options in effect is known in + advance.

+ +

Failure: badarg if the local node is not alive or the + option list is malformed.

+ + + + node() -> Node + Name of the local node + + Node = node() + + +

Returns the name of the local node. If the node is not alive, + nonode@nohost is returned instead.

+

Allowed in guard tests.

+ + + + node(Arg) -> Node + At which node is a pid, port or reference located + + Arg = pid() | port() | ref() + Node = node() + + +

Returns the node where Arg is located. Arg can + be a pid, a reference, or a port. If the local node is not + alive, nonode@nohost is returned.

+

Allowed in guard tests.

+ + + + nodes() -> Nodes + All visible nodes in the system + + Nodes = [node()] + + +

Returns a list of all visible nodes in the system, excluding + the local node. Same as nodes(visible).

+ + + + nodes(Arg | [Arg]) -> Nodes + All nodes of a certain type in the system + + Arg = visible | hidden | connected | this | known + Nodes = [node()] + + +

Returns a list of nodes according to argument given. + The result returned when the argument is a list, is the list + of nodes satisfying the disjunction(s) of the list elements.

+

Arg can be any of the following:

+ + visible + +

Nodes connected to this node through normal connections.

+ + hidden + +

Nodes connected to this node through hidden connections.

+ + connected + +

All nodes connected to this node.

+ + this + +

This node.

+ + known + +

Nodes which are known to this node, i.e., connected, + previously connected, etc.

+ + +

Some equalities: [node()] = nodes(this), + nodes(connected) = nodes([visible, hidden]), and + nodes() = nodes(visible).

+

If the local node is not alive, + nodes(this) == nodes(known) == [nonode@nohost], for + any other Arg the empty list [] is returned.

+ + + + now() -> {MegaSecs, Secs, MicroSecs} + Elapsed time since 00:00 GMT + + MegaSecs = Secs = MicroSecs = int() + + +

Returns the tuple {MegaSecs, Secs, MicroSecs} which is + the elapsed time since 00:00 GMT, January 1, 1970 (zero hour) + on the assumption that the underlying OS supports this. + 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 + now() can be used to generate unique time-stamps. 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.

+ + + + open_port(PortName, PortSettings) -> port() + Open a port + + PortName = {spawn, Command} | {spawn_driver, Command} | {spawn_executable, Command} | {fd, In, Out} +  Command = string() +  In = Out = int() + PortSettings = [Opt] +  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 +   N = 1 | 2 | 4 +   L = int() +   Dir = string() +   Env = [{Name, Val}] +    Name = string() +    Val = string() | false + + +

Returns a port identifier as the result of opening a + new Erlang port. A port can be seen as an external Erlang + process. PortName is one of the following:

+ + {spawn, Command} + +

Starts an external program. Command is the name + of the external program which will be run. Command + runs outside the Erlang work space unless an Erlang + driver with the name Command is found. If found, + that driver will be started. A driver runs in the Erlang + workspace, which means that it is linked with the Erlang + runtime system.

+

When starting external programs on Solaris, the system + call vfork is used in preference to fork + for performance reasons, although it has a history of + being less robust. If there are problems with using + vfork, setting the environment variable + ERL_NO_VFORK to any value will cause fork + to be used instead.

+ +

For external programs, the PATH is searched + (or an equivalent method is used to find programs, + depending on operating system). This is done by invoking + the shell och certain platforms. The first space + separated token of the command will be considered as the + name of the executable (or driver). This (among other + things) makes this option unsuitable for running + programs having spaces in file or directory names. Use + {spawn_executable, Command} instead if spaces in executable + file names is desired.

+ + {spawn_driver, Command} + +

Works like {spawn, Command}, but demands the + first (space separated) token of the command to be the name of a + loaded driver. If no driver with that name is loaded, a + badarg error is raised.

+ + {spawn_executable, Command} + + +

Works like {spawn, Command}, but only runs + external executables. The Command in it's whole + is used as the name of the executable, including any + spaces. If arguments are to be passed, the + args and arg0 PortSettings can be used.

+ +

The shell is not usually invoked to start the + program, it's executed directly. Neither is the + PATH (or equivalent) searched. To find a program + in the PATH to execute, use os:find_executable/1.

+

Only if a shell script or .bat file is + executed, the appropriate command interpreter will + implicitly be invoked, but there will still be no + command argument expansion or implicit PATH search.

+ +

If the Command cannot be run, an error + exception, with the posix error code as the reason, is + raised. The error reason may differ between operating + systems. Typically the error enoent is raised + when one tries to run a program that is not found and + eaccess is raised when the given file is not + executable.

+ + {fd, In, Out} + +

Allows an Erlang process to access any currently opened + file descriptors used by Erlang. The file descriptor + In can be used for standard input, and the file + descriptor Out for standard output. It is only + used for various servers in the Erlang operating system + (shell and user). Hence, its use is very + limited.

+ + +

PortSettings is a list of settings for the port. + Valid settings are:

+ + {packet, N} + +

Messages are preceded by their length, sent in N + bytes, with the most significant byte first. Valid values + for N are 1, 2, or 4.

+ + stream + +

Output messages are sent without packet lengths. A + user-defined protocol must be used between the Erlang + process and the external object.

+ + {line, L} + +

Messages are delivered on a per line basis. Each line + (delimited by the OS-dependent newline sequence) is + delivered in one single message. The message data format + is {Flag, Line}, where Flag is either + eol or noeol and Line is the actual + data delivered (without the newline sequence).

+

L specifies the maximum line length in bytes. + Lines longer than this will be delivered in more than one + message, with the Flag set to noeol for all + but the last message. If end of file is encountered + anywhere else than immediately following a newline + sequence, the last line will also be delivered with + the Flag set to noeol. In all other cases, + lines are delivered with Flag set to eol.

+

The {packet, N} and {line, L} settings are + mutually exclusive.

+ + {cd, Dir} + +

This is only valid for {spawn, Command} and + {spawn_executable, Command}. + The external program starts using Dir as its + working directory. Dir must be a string. Not + available on VxWorks.

+ + {env, Env} + +

This is only valid for {spawn, Command} and + {spawn_executable, Command}. + The environment of the started process is extended using + the environment specifications in Env.

+

Env should be a list of tuples {Name, Val}, + where Name is the name of an environment variable, + and Val is the value it is to have in the spawned + port process. Both Name and Val must be + strings. The one exception is Val being the atom + false (in analogy with os:getenv/1), which + removes the environment variable. Not available on + VxWorks.

+ + {args, [ string() ]} + + +

This option is only valid for {spawn_executable, Command} + and specifies arguments to the executable. Each argument + is given as a separate string and (on Unix) eventually + ends up as one element each in the argument vector. On + other platforms, similar behavior is mimicked.

+ +

The arguments are not expanded by the shell prior to + being supplied to the executable, most notably this + means that file wildcard expansion will not happen. Use + filelib:wildcard/1 + to expand wildcards for the arguments. Note that even if + the program is a Unix shell script, meaning that the + shell will ultimately be invoked, wildcard expansion + will not happen and the script will be provided with the + untouched arguments. On Windows®, wildcard expansion + is always up to the program itself, why this isn't an + issue.

+ +

Note also that the actual executable name (a.k.a. argv[0]) + should not be given in this list. The proper executable name will + automatically be used as argv[0] where applicable.

+ +

If one, for any reason, wants to explicitly set the + program name in the argument vector, the arg0 + option can be used.

+ + + {arg0, string()} + + +

This option is only valid for {spawn_executable, Command} + and explicitly specifies the program name argument when + running an executable. This might in some circumstances, + on some operating systems, be desirable. How the program + responds to this is highly system dependent and no specific + effect is guaranteed.

+ + + + exit_status + +

This is only valid for {spawn, Command} where + Command refers to an external program, and for + {spawn_executable, Command}.

+

When the external process connected to the port exits, a + message of the form {Port,{exit_status,Status}} is + sent to the connected process, where Status is the + exit status of the external process. If the program + aborts, on Unix the same convention is used as the shells + do (i.e., 128+signal).

+

If the eof option has been given as well, + the eof message and the exit_status message + appear in an unspecified order.

+

If the port program closes its stdout without exiting, + the exit_status option will not work.

+ + use_stdio + +

This is only valid for {spawn, Command} and + {spawn_executable, Command}. It + allows the standard input and output (file descriptors 0 + and 1) of the spawned (UNIX) process for communication + with Erlang.

+ + nouse_stdio + +

The opposite of use_stdio. Uses file descriptors + 3 and 4 for communication with Erlang.

+ + stderr_to_stdout + +

Affects ports to external programs. The executed program + gets its standard error file redirected to its standard + output file. stderr_to_stdout and + nouse_stdio are mutually exclusive.

+ + overlapped_io + +

Affects ports to external programs on Windows® only. + 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 + the case for simple port programs, but an option of value for the + experienced Windows programmer. On all other platforms, this + option is silently discarded.

+ + in + +

The port can only be used for input.

+ + out + +

The port can only be used for output.

+ + binary + +

All IO from the port are binary data objects as opposed + to lists of bytes.

+ + eof + +

The port will not be closed at the end of the file and + produce an exit signal. Instead, it will remain open and + a {Port, eof} message will be sent to the process + holding the port.

+ + hide + +

When running on Windows, suppress creation of a new + console window when spawning the port program. + (This option has no effect on other platforms.)

+ + +

The default is stream for all types of port and + use_stdio for spawned ports.

+

Failure: If the port cannot be opened, the exit reason is + badarg, system_limit, or the Posix error code which + most closely describes the error, or einval if no Posix code + is appropriate:

+ + badarg + +

Bad input arguments to open_port.

+ + system_limit + +

All available ports in the Erlang emulator are in use.

+ + enomem + +

There was not enough memory to create the port.

+ + eagain + +

There are no more available operating system processes.

+ + enametoolong + +

The external command given was too long.

+ + emfile + +

There are no more available file descriptors (for the operating system process + that the Erlang emulator runs in).

+ + enfile + +

The file table is full (for the entire operating system).

+ + eacces + +

The Command given in {spawn_executable, Command} does not point out an executable file.

+ + enoent + +

The Command given in {spawn_executable, Command} does not point out an existing file.

+ + +

During use of a port opened using {spawn, Name}, + {spawn_driver, Name} or {spawn_executable, Name}, + errors arising when sending messages to it are reported to + the owning process using signals of the form + {'EXIT', Port, PosixCode}. See file(3) for + possible values of PosixCode.

+

+ The maximum number of ports that can be open at the same + time is 1024 by default, but can be configured by + the environment variable ERL_MAX_PORTS.

+ + + + erlang:phash(Term, Range) -> Hash + Portable hash function + + Term = term() + Range = 1..2^32 + Hash = 1..Range + + +

Portable hash function that will give the same hash for + the same Erlang term regardless of machine architecture and + ERTS version (the BIF was introduced in ERTS 4.9.1.1). Range + can be between 1 and 2^32, the function returns a hash value + for Term within the range 1..Range.

+

This BIF could be used instead of the old deprecated + erlang:hash/2 BIF, as it calculates better hashes for + all data-types, but consider using phash2/1,2 instead.

+ + + + erlang:phash2(Term [, Range]) -> Hash + Portable hash function + + Term = term() + Range = 1..2^32 + Hash = 0..Range-1 + + +

Portable hash function that will give the same hash for + the same Erlang term regardless of machine architecture and + ERTS version (the BIF was introduced in ERTS 5.2). Range can + be between 1 and 2^32, the function returns a hash value for + Term within the range 0..Range-1. When called + without the Range argument, a value in the range + 0..2^27-1 is returned.

+

This BIF should always be used for hashing terms. It + distributes small integers better than phash/2, and + it is faster for bignums and binaries.

+

Note that the range 0..Range-1 is different from + the range of phash/2 (1..Range).

+ + + + pid_to_list(Pid) -> string() + Text representation of a pid + + Pid = pid() + + +

Returns a string which corresponds to the text + representation of Pid.

+ +

This BIF is intended for debugging and for use in + the Erlang operating system. It should not be used in + application programs.

+ + + + + port_close(Port) -> true + Close an open port + + Port = port() | atom() + + +

Closes an open port. Roughly the same as + Port ! {self(), close} except for the error behaviour + (see below), and that the port does not reply with + {Port, closed}. Any process may close a port with + port_close/1, not only the port owner (the connected + process).

+

For comparison: Port ! {self(), close} fails with + badarg if Port cannot be sent to (i.e., + Port refers neither to a port nor to a process). If + Port is a closed port nothing happens. If Port + is an open port and the calling process is the port owner, + the port replies with {Port, closed} when all buffers + have been flushed and the port really closes, but if + the calling process is not the port owner the port owner fails with badsig.

+

Note that any process can close a port using + Port ! {PortOwner, close} just as if it itself was + the port owner, but the reply always goes to the port owner.

+

In short: port_close(Port) has a cleaner and more + logical behaviour than Port ! {self(), close}.

+

Failure: badarg if Port is not an open port or + the registered name of an open port.

+ + + + port_command(Port, Data) -> true + Send data to a port + + Port = port() | atom() + Data = iodata() + + +

Sends data to a port. Same as + Port ! {self(), {command, Data}} except for the error + behaviour (see below). Any process may send data to a port + with port_command/2, not only the port owner + (the connected process).

+

For comparison: Port ! {self(), {command, Data}} + fails with badarg if Port cannot be sent to + (i.e., Port refers neither to a port nor to a process). + If Port is a closed port the data message disappears + without a sound. If Port is open and the calling + process is not the port owner, the port owner fails + with badsig. The port owner fails with badsig + also if Data is not a valid IO list.

+

Note that any process can send to a port using + Port ! {PortOwner, {command, Data}} just as if it + itself was the port owner.

+

In short: port_command(Port, Data) has a cleaner and + more logical behaviour than + Port ! {self(), {command, Data}}.

+

If the port is busy, the calling process will be suspended + until the port is not busy anymore.

+

Failures:

+ + badarg + + If Port is not an open port or the registered name + of an open port. + + badarg + + If Data is not a valid io list. + + + + + + erlang:port_command(Port, Data, OptionList) -> true|false + Send data to a port + + Port = port() | atom() + Data = iodata() + OptionList = [Option] + Option = force + Option = nosuspend + + +

Sends data to a port. port_command(Port, Data, []) + equals port_command(Port, Data).

+

If the port command is aborted false is returned; + otherwise, true is returned.

+

If the port is busy, the calling process will be suspended + until the port is not busy anymore.

+

Currently the following Options are valid:

+ + force + The calling process will not be suspended if the port is + busy; instead, the port command is forced through. The + call will fail with a notsup exception if the + driver of the port does not support this. For more + information see the + + driver flag. + + nosuspend + The calling process will not be suspended if the port is + busy; instead, the port command is aborted and + false is returned. + + + +

More options may be added in the future.

+ + +

erlang:port_command/3 is currently not auto imported, but + it is planned to be auto imported in OTP R14.

+ +

Failures:

+ + badarg + + If Port is not an open port or the registered name + of an open port. + + badarg + + If Data is not a valid io list. + + badarg + + If OptionList is not a valid option list. + + notsup + + If the force option has been passed, but the + driver of the port does not allow forcing through + a busy port. + + + + + + port_connect(Port, Pid) -> true + Set the owner of a port + + Port = port() | atom() + Pid = pid() + + +

Sets the port owner (the connected port) to Pid. + Roughly the same as Port ! {self(), {connect, Pid}} + except for the following:

+ + +

The error behavior differs, see below.

+ + +

The port does not reply with + {Port,connected}.

+ + +

The new port owner gets linked to the port.

+ + +

The old port owner stays linked to the port and have to call + unlink(Port) if this is not desired. Any process may + set the port owner to be any process with + port_connect/2.

+

For comparison: Port ! {self(), {connect, Pid}} fails + with badarg if Port cannot be sent to (i.e., + Port refers neither to a port nor to a process). If + Port is a closed port nothing happens. If Port + is an open port and the calling process is the port owner, + the port replies with {Port, connected} to the old + port owner. Note that the old port owner is still linked to + the port, and that the new is not. If Port is an open + port and the calling process is not the port owner, + the port owner fails with badsig. The port + owner fails with badsig also if Pid is not an + existing local pid.

+

Note that any process can set the port owner using + Port ! {PortOwner, {connect, Pid}} just as if it + itself was the port owner, but the reply always goes to + the port owner.

+

In short: port_connect(Port, Pid) has a cleaner and + more logical behaviour than + Port ! {self(),{connect,Pid}}.

+

Failure: badarg if Port is not an open port + or the registered name of an open port, or if Pid is + not an existing local pid.

+ + + + port_control(Port, Operation, Data) -> Res + Perform a synchronous control operation on a port + + Port = port() | atom() + Operation = int() + Data = Res = iodata() + + +

Performs a synchronous control operation on a port. + The meaning of Operation and Data depends on + the port, i.e., on the port driver. Not all port drivers + support this control feature.

+

Returns: a list of integers in the range 0 through 255, or a + binary, depending on the port driver. The meaning of + the returned data also depends on the port driver.

+

Failure: badarg if Port is not an open port or + the registered name of an open port, if Operation + cannot fit in a 32-bit integer, if the port driver does not + support synchronous control operations, or if the port driver + so decides for any reason (probably something wrong with + Operation or Data).

+ + + + erlang:port_call(Port, Operation, Data) -> term() + Synchronous call to a port with term data + + Port = port() | atom() + Operation = int() + Data = term() + + +

Performs a synchronous call to a port. The meaning of + Operation and Data depends on the port, i.e., + on the port driver. Not all port drivers support this feature.

+

Port is a port identifier, referring to a driver.

+

Operation is an integer, which is passed on to + the driver.

+

Data is any Erlang term. This data is converted to + binary term format and sent to the port.

+

Returns: a term from the driver. The meaning of the returned + data also depends on the port driver.

+

Failure: badarg if Port is not an open port or + the registered name of an open port, if Operation + cannot fit in a 32-bit integer, if the port driver does not + support synchronous control operations, or if the port driver + so decides for any reason (probably something wrong with + Operation or Data).

+ + + + erlang:port_info(Port) -> [{Item, Info}] | undefined + Information about a port + + Port = port() | atom() + Item, Info -- see below + + +

Returns a list containing tuples with information about + the Port, or undefined if the port is not open. + The order of the tuples is not defined, nor are all the + tuples mandatory.

+ + {registered_name, RegName} + +

RegName (an atom) is the registered name of + the port. If the port has no registered name, this tuple + is not present in the list.

+ + {id, Index} + +

Index (an integer) is the internal index of the + port. This index may be used to separate ports.

+ + {connected, Pid} + +

Pid is the process connected to the port.

+ + {links, Pids} + +

Pids is a list of pids to which processes the + port is linked.

+ + {name, String} + +

String is the command name set by + open_port.

+ + {input, Bytes} + +

Bytes is the total number of bytes read from + the port.

+ + {output, Bytes} + +

Bytes is the total number of bytes written to + the port.

+ + +

Failure: badarg if Port is not a local port.

+ + + + erlang:port_info(Port, Item) -> {Item, Info} | undefined | [] + Information about a port + + Port = port() | atom() + Item, Info -- see below + + +

Returns information about Port as specified + by Item, or undefined if the port is not open. + Also, if Item == registered_name and the port has no + registered name, [] is returned.

+

For valid values of Item, and corresponding + values of Info, see + erlang:port_info/1.

+

Failure: badarg if Port is not a local port.

+ + + + erlang:port_to_list(Port) -> string() + Text representation of a port identifier + + Port = port() + + +

Returns a string which corresponds to the text + representation of the port identifier Port.

+ +

This BIF is intended for debugging and for use in + the Erlang operating system. It should not be used in + application programs.

+ + + + + erlang:ports() -> [port()] + All open ports + +

Returns a list of all ports on the local node.

+ + + + pre_loaded() -> [Module] + List of all pre-loaded modules + + Module = atom() + + +

Returns a list of Erlang modules which are pre-loaded in + the system. As all loading of code is done through the file + system, the file system must have been loaded previously. + Hence, at least the module init must be pre-loaded.

+ + + + erlang:process_display(Pid, Type) -> void() + Write information about a local process on standard error + + Pid = pid() + Type = backtrace + + +

Writes information about the local process Pid on + standard error. The currently allowed value for the atom + Type is backtrace, which shows the contents of + the call stack, including information about the call chain, with + the current function printed first. The format of the output + is not further defined.

+ + + + process_flag(Flag, Value) -> OldValue + Set process flags for the calling process + + Flag, Value, OldValue -- see below + + +

Sets certain flags for the process which calls this + function. Returns the old value of the flag.

+ + process_flag(trap_exit, Boolean) + +

When trap_exit is set to true, exit signals + arriving to a process are converted to {'EXIT', From, Reason} messages, which can be received as ordinary + messages. If trap_exit is set to false, the + process exits if it receives an exit signal other than + normal and the exit signal is propagated to its + linked processes. Application processes should normally + not trap exits.

+

See also exit/2.

+ + process_flag(error_handler, Module) + +

This is used by a process to redefine the error handler + for undefined function calls and undefined registered + processes. Inexperienced users should not use this flag + since code auto-loading is dependent on the correct + operation of the error handling module.

+ + process_flag(min_heap_size, MinHeapSize) + +

This changes the minimum heap size for the calling + process.

+ + process_flag(priority, Level) + + +

This sets the process priority. Level is an atom. + There are currently four priority levels: low, + normal, high, and max. The default + priority level is normal. NOTE: The + max priority level is reserved for internal use in + the Erlang runtime system, and should not be used + by others. +

+

Internally in each priority level processes are scheduled + in a round robin fashion. +

+

Execution of processes on priority normal and + priority low will be interleaved. Processes on + priority low will be selected for execution less + frequently than processes on priority normal. +

+

When there are runnable processes on priority high + no processes on priority low, or normal will + be selected for execution. Note, however, that this does + not mean that no processes on priority low, + or normal will be able to run when there are + processes on priority high running. On the runtime + system with SMP support there might be more processes running + in parallel than processes on priority high, i.e., + a low, and a high priority process might + execute at the same time. +

+

When there are runnable processes on priority max + no processes on priority low, normal, or + high will be selected for execution. As with the + high priority, processes on lower priorities might + execute in parallel with processes on priority max. +

+

Scheduling is preemptive. Regardless of priority, a process + is preempted when it has consumed more than a certain amount + of reductions since the last time it was selected for + execution. +

+

NOTE: You should not depend on the scheduling + to remain exactly as it is today. Scheduling, at least on + the runtime system with SMP support, is very likely to be + modified in the future in order to better utilize available + processor cores. +

+

There is currently no automatic mechanism for + avoiding priority inversion, such as priority inheritance, + or priority ceilings. When using priorities you have + to take this into account and handle such scenarios by + yourself. +

+

Making calls from a high priority process into code + that you don't have control over may cause the high + priority process to wait for a processes with lower + priority, i.e., effectively decreasing the priority of the + high priority process during the call. Even if this + isn't the case with one version of the code that you don't + have under your control, it might be the case in a future + version of it. This might, for example, happen if a + high priority process triggers code loading, since + the code server runs on priority normal. +

+

Other priorities than normal are normally not needed. + When other priorities are used, they need to be used + with care, especially the high priority must + be used with care. A process on high priority should + only perform work for short periods of time. Busy looping for + long periods of time in a high priority process will + most likely cause problems, since there are important servers + in OTP running on priority normal. +

+ + + process_flag(save_calls, N) + +

When there are runnable processes on priority max + no processes on priority low, normal, or + high will be selected for execution. As with the + high priority, processes on lower priorities might + execute in parallel with processes on priority max. +

+

N must be an integer in the interval 0..10000. + If N > 0, call saving is made active for the + process, which means that information about the N + most recent global function calls, BIF calls, sends and + receives made by the process are saved in a list, which + can be retrieved with + process_info(Pid, last_calls). A global function + call is one in which the module of the function is + explicitly mentioned. Only a fixed amount of information + is saved: a tuple {Module, Function, Arity} for + function calls, and the mere atoms send, + 'receive' and timeout for sends and receives + ('receive' when a message is received and + timeout when a receive times out). If N = 0, + call saving is disabled for the process, which is the + default. Whenever the size of the call saving list is set, + its contents are reset.

+ + process_flag(sensitive, Boolean) + +

Set or clear the sensitive flag for the current process. + When a process has been marked as sensitive by calling + process_flag(sensitive, true), features in the run-time + system that can be used for examining the data and/or inner working + of the process are silently disabled.

+

Features that are disabled include (but are not limited to) + the following:

+

Tracing: Trace flags can still be set for the process, but no + trace messages of any kind will be generated. + (If the sensitive flag is turned off, trace messages will + again be generated if there are any trace flags set.)

+

Sequential tracing: The sequential trace token will be propagated + as usual, but no sequential trace messages will be generated.

+

process_info/1,2 cannot be used to read out the message + queue or the process dictionary (both will be returned as empty lists).

+

Stack back-traces cannot be displayed for the process.

+

In crash dumps, the stack, messages, and the process dictionary + will be omitted.

+

If {save_calls,N} has been set for the process, no + function calls will be saved to the call saving list. + (The call saving list will not be cleared; furthermore, send, receive, + and timeout events will still be added to the list.)

+ + + + + + process_flag(Pid, Flag, Value) -> OldValue + Set process flags for a process + + Pid = pid() + Flag, Value, OldValue -- see below + + +

Sets certain flags for the process Pid, in the same + manner as + process_flag/2. + Returns the old value of the flag. The allowed values for + Flag are only a subset of those allowed in + process_flag/2, namely: save_calls.

+

Failure: badarg if Pid is not a local process.

+ + + + process_info(Pid) -> InfoResult + Information about a process + + Pid = pid() + Item = atom() + Info = term() + InfoTuple = {Item, Info} + InfoTupleList = [InfoTuple] + InfoResult = InfoTupleList | undefined + + +

Returns a list containing InfoTuples with + miscellaneous information about the process identified by + Pid, or undefined if the process is not alive. +

+

+ The order of the InfoTuples is not defined, nor + are all the InfoTuples mandatory. The InfoTuples + part of the result may be changed without prior notice. + Currently InfoTuples with the following Items + are part of the result: + current_function, initial_call, status, + message_queue_len, messages, links, + dictionary, trap_exit, error_handler, + priority, group_leader, total_heap_size, + heap_size, stack_size, reductions, and + garbage_collection. + If the process identified by Pid has a registered name + also an InfoTuple with Item == registered_name + will appear. +

+

See process_info/2 + for information about specific InfoTuples.

+ +

This BIF is intended for debugging only, use + process_info/2 + for all other purposes. +

+ +

Failure: badarg if Pid is not a local process.

+ + + + process_info(Pid, ItemSpec) -> InfoResult + Information about a process + + Pid = pid() + Item = atom() + Info = term() + ItemList = [Item] + ItemSpec = Item | ItemList + InfoTuple = {Item, Info} + InfoTupleList = [InfoTuple] + InfoResult = InfoTuple | InfoTupleList | undefined | [] + + +

Returns information about the process identified by Pid + as specified by the ItemSpec, or undefined if the + process is not alive. +

+

If the process is alive and ItemSpec is a single + Item, the returned value is the corresponding + InfoTuple unless ItemSpec == registered_name + and the process has no registered name. In this case + [] is returned. This strange behavior is due to + historical reasons, and is kept for backward compatibility. +

+

If ItemSpec is an ItemList, the result is an + InfoTupleList. The InfoTuples in the + InfoTupleList will appear with the corresponding + Items in the same order as the Items appeared + in the ItemList. Valid Items may appear multiple + times in the ItemList. +

+

If registered_name is part of an ItemList + and the process has no name registered a + {registered_name, []} InfoTuple will + appear in the resulting InfoTupleList. This + behavior is different than when + ItemSpec == registered_name, and than when + process_info/1 is used. +

+

Currently the following InfoTuples with corresponding + Items are valid:

+ + {backtrace, Bin} + +

The binary Bin contains the same information as + the output from + erlang:process_display(Pid, backtrace). Use + binary_to_list/1 to obtain the string of characters + from the binary.

+ + {binary, BinInfo} + +

BinInfo is a list containing miscellaneous information + about binaries currently being referred to by this process. + This InfoTuple may be changed or removed without prior + notice.

+ + {catchlevel, CatchLevel} + +

CatchLevel is the number of currently active + catches in this process. This InfoTuple may be + changed or removed without prior notice.

+ + {current_function, {Module, Function, Args}} + +

Module, Function, Args is + the current function call of the process.

+ + {dictionary, Dictionary} + +

Dictionary is the dictionary of the process.

+ + {error_handler, Module} + +

Module is the error handler module used by + the process (for undefined function calls, for example).

+ + {garbage_collection, GCInfo} + +

GCInfo is a list which contains miscellaneous + information about garbage collection for this process. + The content of GCInfo may be changed without + prior notice.

+ + {group_leader, GroupLeader} + +

GroupLeader is group leader for the IO of + the process.

+ + {heap_size, Size} + +

Size is the size in words of youngest heap generation + of the process. This generation currently include the stack + of the process. This information is highly implementation + dependent, and may change if the implementation change. +

+ + {initial_call, {Module, Function, Arity}} + +

Module, Function, Arity is + the initial function call with which the process was + spawned.

+ + {links, Pids} + +

Pids is a list of pids, with processes to + which the process has a link.

+ + {last_calls, false|Calls} + +

The value is false if call saving is not active + for the process (see + process_flag/3). + If call saving is active, a list is returned, in which + the last element is the most recent called.

+ + {memory, Size} + +

Size is the size in bytes of the process. This + includes call stack, heap and internal structures.

+ + {message_binary, BinInfo} + +

BinInfo is a list containing miscellaneous information + about binaries currently being referred to by the message + area. This InfoTuple is only valid on an emulator + using the hybrid heap type. This InfoTuple may be + changed or removed without prior notice.

+ + {message_queue_len, MessageQueueLen} + +

MessageQueueLen is the number of messages + currently in the message queue of the process. This is + the length of the list MessageQueue returned as + the info item messages (see below).

+ + {messages, MessageQueue} + +

MessageQueue is a list of the messages to + the process, which have not yet been processed.

+ + {monitored_by, Pids} + +

A list of pids that are monitoring the process (with + erlang:monitor/2).

+ + {monitors, Monitors} + +

A list of monitors (started by erlang:monitor/2) + that are active for the process. For a local process + monitor or a remote process monitor by pid, the list item + is {process, Pid}, and for a remote process + monitor by name, the list item is + {process, {RegName, Node}}.

+ + {priority, Level} + +

Level is the current priority level for + the process. For more information on priorities see + process_flag(priority, Level).

+ + {reductions, Number} + +

Number is the number of reductions executed by + the process.

+ + {registered_name, Atom} + +

Atom is the registered name of the process. If + the process has no registered name, this tuple is not + present in the list.

+ + {sequential_trace_token, [] | SequentialTraceToken} + +

SequentialTraceToken the sequential trace token for + the process. This InfoTuple may be changed or removed + without prior notice.

+ + {stack_size, Size} + +

Size is the stack size of the process in words.

+ + {status, Status} + +

Status is the status of the process. Status + is waiting (waiting for a message), running, + runnable (ready to run, but another process is + running), or suspended (suspended on a "busy" port + or by the erlang:suspend_process/[1,2] BIF).

+ + {suspending, SuspendeeList} + +

SuspendeeList is a list of {Suspendee, + ActiveSuspendCount, OutstandingSuspendCount} tuples. + Suspendee is the pid of a process that have been or is to + be suspended by the process identified by Pid via the + erlang:suspend_process/2 + BIF, or the + erlang:suspend_process/1 + BIF. ActiveSuspendCount is the number of times the + Suspendee has been suspended by Pid. + OutstandingSuspendCount is the number of not yet + completed suspend requests sent by Pid. That is, + if ActiveSuspendCount /= 0, Suspendee is + currently in the suspended state, and if + OutstandingSuspendCount /= 0 the asynchronous + option of erlang:suspend_process/2 has been used and + the suspendee has not yet been suspended by Pid. + Note that the ActiveSuspendCount and + OutstandingSuspendCount are not the total suspend count + on Suspendee, only the parts contributed by Pid. +

+ + {total_heap_size, Size} + +

Size is the total size in words of all heap + fragments of the process. This currently include the stack + of the process. +

+ + {trace, InternalTraceFlags} + +

InternalTraceFlags is an integer representing + internal trace flag for this process. This InfoTuple + may be changed or removed without prior notice.

+ + {trap_exit, Boolean} + +

Boolean is true if the process is trapping + exits, otherwise it is false.

+ + +

Note however, that not all implementations support every one + of the above Items.

+

Failure: badarg if Pid is not a local process, + or if Item is not a valid Item.

+ + + + processes() -> [pid()] + All processes + +

Returns a list of process identifiers corresponding to + all the processes currently existing on the local node. +

+

Note that a process that is exiting, exists but is not alive, i.e., + is_process_alive/1 will return false for a process + that is exiting, but its process identifier will be part + of the result returned from processes/0. +

+ 
+> processes().
+[<0.0.0>,<0.2.0>,<0.4.0>,<0.5.0>,<0.7.0>,<0.8.0>]
+ + + + purge_module(Module) -> void() + Remove old code for a module + + Module = atom() + + +

Removes old code for Module. Before this BIF is used, + erlang:check_process_code/2 should be called to check + that no processes are executing old code in the module.

+ +

This BIF is intended for the code server (see + code(3)) and should not be + used elsewhere.

+ +

Failure: badarg if there is no old code for + Module.

+ + + + put(Key, Val) -> OldVal | undefined + Add a new value to the process dictionary + + Key = Val = OldVal = term() + + +

Adds a new Key to the process dictionary, associated + with the value Val, and returns undefined. If + Key already exists, the old value is deleted and + replaced by Val and the function returns the old value.

+ +

The values stored when put is evaluated within + the scope of a catch will not be retracted if a + throw is evaluated, or if an error occurs.

+ + 
+> X = put(name, walrus), Y = put(name, carpenter),
+Z = get(name),
+{X, Y, Z}.
+{undefined,walrus,carpenter}
+ + + + erlang:raise(Class, Reason, Stacktrace) + Stop execution with an exception of given class, reason and call stack backtrace + + Class = error | exit | throw + Reason = term() + Stacktrace = [{Module, Function, Arity | Args} | {Fun, Args}] +  Module = Function = atom() +  Arity = int() +  Args = [term()] +  Fun = [fun()] + + +

Stops the execution of the calling process with an + exception of given class, reason and call stack backtrace + (stacktrace).

+ +

This BIF is intended for debugging and for use in + the Erlang operating system. In general, it should + be avoided in applications, unless you know + very well what you are doing.

+ +

Class is one of error, exit or + throw, so if it were not for the stacktrace + erlang:raise(Class, Reason, Stacktrace) is + equivalent to erlang:Class(Reason). + Reason is any term and Stacktrace is a list as + returned from get_stacktrace(), that is a list of + 3-tuples {Module, Function, Arity | Args} where + Module and Function are atoms and the third + element is an integer arity or an argument list. The + stacktrace may also contain {Fun, Args} tuples where + Fun is a local fun and Args is an argument list.

+

The stacktrace is used as the exception stacktrace for the + calling process; it will be truncated to the current + maximum stacktrace depth.

+

Because evaluating this function causes the process to + terminate, it has no return value - unless the arguments are + invalid, in which case the function returns the error reason, that is badarg. If you want to be + really sure not to return you can call + erlang:error(erlang:raise(Class, Reason, Stacktrace)) + and hope to distinguish exceptions later.

+ + + + erlang:read_timer(TimerRef) -> int() | false + Number of milliseconds remaining for a timer + + TimerRef = ref() + + +

TimerRef is a timer reference returned by + erlang:send_after/3 + or + erlang:start_timer/3. + If the timer is active, the function returns the time in + milliseconds left until the timer will expire, otherwise + false (which means that TimerRef was never a + timer, that it has been cancelled, or that it has already + delivered its message).

+

See also + erlang:send_after/3, + erlang:start_timer/3, + and + erlang:cancel_timer/1.

+ + + + erlang:ref_to_list(Ref) -> string() + Text representation of a reference + + Ref = ref() + + +

Returns a string which corresponds to the text + representation of Ref.

+ +

This BIF is intended for debugging and for use in + the Erlang operating system. It should not be used in + application programs.

+ + + + + register(RegName, Pid | Port) -> true + Register a name for a pid (or port) + + RegName = atom() + Pid = pid() + Port = port() + + +

Associates the name RegName with a pid or a port + identifier. RegName, which must be an atom, can be used + instead of the pid / port identifier in the send operator + (RegName ! Message).

+ 
+> register(db, Pid).
+true
+

Failure: badarg if Pid is not an existing, + local process or port, if RegName is already in use, + if the process or port is already registered (already has a + name), or if RegName is the atom undefined.

+ + + + registered() -> [RegName] + All registered names + + RegName = atom() + + +

Returns a list of names which have been registered using + register/2.

+ 
+> registered().
+[code_server, file_server, init, user, my_db]
+ + + + erlang:resume_process(Suspendee) -> true + Resume a suspended process + + Suspendee = pid() + + +

Decreases the suspend count on the process identified by + Suspendee. Suspendee should previously have been + suspended via + erlang:suspend_process/2, + or + erlang:suspend_process/1 + by the process calling erlang:resume_process(Suspendee). When + the suspend count on Suspendee reach zero, Suspendee + will be resumed, i.e., the state of the Suspendee is changed + from suspended into the state Suspendee was in before it was + suspended. +

+ +

This BIF is intended for debugging only.

+ +

Failures:

+ + badarg + + If Suspendee isn't a process identifier. + + badarg + + If the process calling erlang:resume_process/1 had + not previously increased the suspend count on the process + identified by Suspendee. + + badarg + + If the process identified by Suspendee is not alive. + + + + + + round(Number) -> int() + Return an integer by rounding a number + + Number = number() + + +

Returns an integer by rounding Number.

+ 
+> round(5.5).
+6
+

Allowed in guard tests.

+ + + + self() -> pid() + Pid of the calling process + +

Returns the pid (process identifier) of the calling process.

+ 
+> self().
+<0.26.0>
+

Allowed in guard tests.

+ + + + erlang:send(Dest, Msg) -> Msg + Send a message + + Dest = pid() | port() | RegName | {RegName, Node} + Msg = term() +  RegName = atom() +  Node = node() + + +

Sends a message and returns Msg. This is the same as + Dest ! Msg.

+

Dest may be a remote or local pid, a (local) port, a + locally registered name, or a tuple {RegName, Node} + for a registered name at another node.

+ + + + erlang:send(Dest, Msg, [Option]) -> Res + Send a message conditionally + + Dest = pid() | port() | RegName | {RegName, Node} +  RegName = atom() +  Node = node() + Msg = term() + Option = nosuspend | noconnect + Res = ok | nosuspend | noconnect + + +

Sends a message and returns ok, or does not send + the message but returns something else (see below). Otherwise + the same as + erlang:send/2. See + also + erlang:send_nosuspend/2,3. + for more detailed explanation and warnings.

+

The possible options are:

+ + nosuspend + +

If the sender would have to be suspended to do the send, + nosuspend is returned instead.

+ + noconnect + +

If the destination node would have to be auto-connected + before doing the send, noconnect is returned + instead.

+ + + +

As with erlang:send_nosuspend/2,3: Use with extreme + care!

+ + + + + erlang:send_after(Time, Dest, Msg) -> TimerRef + Start a timer + + Time = int() +  0 <= Time <= 4294967295 + Dest = pid() | RegName +  LocalPid = pid() (of a process, alive or dead, on the local node) + Msg = term() + TimerRef = ref() + + +

Starts a timer which will send the message Msg + to Dest after Time milliseconds.

+

If Dest is an atom, it is supposed to be the name of + a registered process. The process referred to by the name is + looked up at the time of delivery. No error is given if + the name does not refer to a process.

+

If Dest is a pid, the timer will be automatically + canceled if the process referred to by the pid is not alive, + or when the process exits. This feature was introduced in + erts version 5.4.11. Note that timers will not be + automatically canceled when Dest is an atom.

+

See also + erlang:start_timer/3, + erlang:cancel_timer/1, + and + erlang:read_timer/1.

+

Failure: badarg if the arguments does not satisfy + the requirements specified above.

+ + + + erlang:send_nosuspend(Dest, Msg) -> bool() + Try to send a message without ever blocking + + Dest = pid() | port() | RegName | {RegName, Node} +  RegName = atom() +  Node = node() + Msg = term() + + +

The same as + erlang:send(Dest, Msg, [nosuspend]), but returns true if + the message was sent and false if the message was not + sent because the sender would have had to be suspended.

+

This function is intended for send operations towards an + unreliable remote node without ever blocking the sending + (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 will not send the message but return false instead.

+

The same happens, if Dest refers to a local port that + is busy. For all other destinations (allowed for the ordinary + send operator '!') this function sends the message and + returns true.

+

This function is only to be used in very rare circumstances + where a process communicates with Erlang nodes that can + disappear without any trace causing the TCP buffers and + the drivers queue to be over-full before the node will actually + be shut down (due to tick timeouts) by net_kernel. The + normal reaction to take when this happens is some kind of + premature shutdown of the other node.

+

Note that ignoring the return value from this function would + result in unreliable message passing, which is + contradictory to the Erlang programming model. The message is + not sent if this function returns false.

+

Note also that in many systems, transient states of + overloaded queues are normal. The fact that this function + returns false does not in any way mean that the other + node is guaranteed to be non-responsive, it could be a + temporary overload. Also a return value of true does + only mean that the message could be sent on the (TCP) channel + without blocking, the message is not guaranteed to have + arrived at the remote node. Also in the case of a disconnected + non-responsive node, the return value is true (mimics + the behaviour of the ! operator). The expected + behaviour as well as the actions to take when the function + returns false are application and hardware specific.

+ +

Use with extreme care!

+ + + + + erlang:send_nosuspend(Dest, Msg, Options) -> bool() + Try to send a message without ever blocking + + Dest = pid() | port() | RegName | {RegName, Node} +  RegName = atom() +  Node = node() + Msg = term() + Option = noconnect + + +

The same as + erlang:send(Dest, Msg, [nosuspend | Options]), + but with boolean return value.

+

This function behaves like + erlang:send_nosuspend/2), + but takes a third parameter, a list of options. The only + currently implemented option is noconnect. The option + noconnect makes the function return false if + the remote node is not currently reachable by the local + node. The normal behaviour is to try to connect to the node, + which may stall the process for a shorter period. The use of + the noconnect option makes it possible to be + absolutely sure not to get even the slightest delay when + sending to a remote process. This is especially useful when + communicating with nodes who expect to always be + the connecting part (i.e. nodes written in C or Java).

+

Whenever the function returns false (either when a + suspend would occur or when noconnect was specified and + the node was not already connected), the message is guaranteed + not to have been sent.

+ +

Use with extreme care!

+ + + + + erlang:set_cookie(Node, Cookie) -> true + Set the magic cookie of a node + + Node = node() + Cookie = atom() + + +

Sets the magic cookie of Node to the atom + Cookie. If Node is the local node, the function + also sets the cookie of all other unknown nodes to + Cookie (see + Distributed Erlang in the Erlang Reference Manual).

+

Failure: function_clause if the local node is not + alive.

+ + + + setelement(Index, Tuple1, Value) -> Tuple2 + Set Nth element of a tuple + + Index = 1..tuple_size(Tuple1) + Tuple1 = Tuple2 = tuple() + Value = term() + + +

Returns a tuple which is a copy of the argument Tuple1 + with the element given by the integer argument Index + (the first element is the element with index 1) replaced by + the argument Value.

+ 
+> setelement(2, {10, green, bottles}, red).
+{10,red,bottles}
+ + + + size(Item) -> int() + Size of a tuple or binary + + Item = tuple() | binary() + + +

Returns an integer which is the size of the argument + Item, which must be either a tuple or a binary.

+ 
+> size({morni, mulle, bwange}).
+3
+

Allowed in guard tests.

+ + + + spawn(Fun) -> pid() + Create a new process with a fun as entry point + + Fun = fun() + + +

Returns the pid of a new process started by the application + of Fun to the empty list []. Otherwise works + like spawn/3.

+ + + + spawn(Node, Fun) -> pid() + Create a new process with a fun as entry point on a given node + + Node = node() + Fun = fun() + + +

Returns the pid of a new process started by the application + of Fun to the empty list [] on Node. If + Node does not exist, a useless pid is returned. + Otherwise works like + spawn/3.

+ + + + spawn(Module, Function, Args) -> pid() + Create a new process with a function as entry point + + Module = Function = atom() + Args = [term()] + + +

Returns the pid of a new process started by the application + of Module:Function to Args. The new process + created will be placed in the system scheduler queue and be + run some time later.

+

error_handler:undefined_function(Module, Function, Args) is evaluated by the new process if + Module:Function/Arity does not exist (where + Arity is the length of Args). The error handler + can be redefined (see + process_flag/2). + If error_handler is undefined, or the user has + redefined the default error_handler its replacement is + undefined, a failure with the reason undef will occur.

+ 
+> spawn(speed, regulator, [high_speed, thin_cut]).
+<0.13.1>
+ + + + spawn(Node, Module, Function, ArgumentList) -> pid() + Create a new process with a function as entry point on a given node + + Node = node() + Module = Function = atom() + Args = [term()] + + +

Returns the pid of a new process started by the application + of Module:Function to Args on Node. If + Node does not exists, a useless pid is returned. + Otherwise works like + spawn/3.

+ + + + spawn_link(Fun) -> pid() + Create and link to a new process with a fun as entry point + + Fun = fun() + + +

Returns the pid of a new process started by the application + of Fun to the empty list []. A link is created between + the calling process and the new process, atomically. + Otherwise works like + spawn/3.

+ + + + spawn_link(Node, Fun) -> + Create and link to a new process with a fun as entry point on a specified node + + Node = node() + Fun = fun() + + +

Returns the pid of a new process started by the application + of Fun to the empty list [] on Node. A link is + created between the calling process and the new process, + atomically. If Node does not exist, a useless pid is + returned (and due to the link, an exit signal with exit + reason noconnection will be received). Otherwise works + like spawn/3.

+ + + + spawn_link(Module, Function, Args) -> pid() + Create and link to a new process with a function as entry point + + Module = Function = atom() + Args = [term()] + + +

Returns the pid of a new process started by the application + of Module:Function to Args. A link is created + between the calling process and the new process, atomically. + Otherwise works like + spawn/3.

+ + + + spawn_link(Node, Module, Function, Args) -> pid() + Create and link to a new process with a function as entry point on a given node + + Node = node() + Module = Function = atom() + Args = [term()] + + +

Returns the pid of a new process started by the application + of Module:Function to Args on Node. A + link is created between the calling process and the new + process, atomically. If Node does not exist, a useless + pid is returned (and due to the link, an exit signal with exit + reason noconnection will be received). Otherwise works + like spawn/3.

+ + + + spawn_monitor(Fun) -> {pid(),reference()} + Create and monitor a new process with a fun as entry point + + Fun = fun() + + +

Returns the pid of a new process started by the application + of Fun to the empty list [] and reference for a monitor + created to the new process. + Otherwise works like + spawn/3.

+ + + + spawn_monitor(Module, Function, Args) -> {pid(),reference()} + Create and monitor a new process with a function as entry point + + Module = Function = atom() + Args = [term()] + + +

A new process is started by the application + of Module:Function to Args, and the process is + monitored at the same time. Returns the pid and a reference + for the monitor. + Otherwise works like + spawn/3.

+ + + + spawn_opt(Fun, [Option]) -> pid() | {pid(),reference()} + Create a new process with a fun as entry point + + Fun = fun() + Option = link | monitor | {priority, Level} | {fullsweep_after, Number} | {min_heap_size, Size} +  Level = low | normal | high +  Number = int() +  Size = int() + + +

Returns the pid of a new process started by the application + of Fun to the empty list []. Otherwise + works like + spawn_opt/4.

+

If the option monitor is given, the newly created + process will be monitored and both the pid and reference for + the monitor will be returned.

+ + + + spawn_opt(Node, Fun, [Option]) -> pid() + Create a new process with a fun as entry point on a given node + + Node = node() + Fun = fun() + Option = link | {priority, Level} | {fullsweep_after, Number} | {min_heap_size, Size} +  Level = low | normal | high +  Number = int() +  Size = int() + + +

Returns the pid of a new process started by the application + of Fun to the empty list [] on Node. If + Node does not exist, a useless pid is returned. + Otherwise works like + spawn_opt/4.

+ + + + spawn_opt(Module, Function, Args, [Option]) -> pid() | {pid(),reference()} + Create a new process with a function as entry point + + Module = Function = atom() + Args = [term()] + Option = link | monitor | {priority, Level} | {fullsweep_after, Number} | {min_heap_size, Size} +  Level = low | normal | high +  Number = int() +  Size = int() + + +

Works exactly like + spawn/3, except that an + extra option list is given when creating the process.

+

If the option monitor is given, the newly created + process will be monitored and both the pid and reference for + the monitor will be returned.

+ + link + +

Sets a link to the parent process (like + spawn_link/3 does).

+ + monitor + +

Monitor the new process (just like + erlang:monitor/2 does).

+ + {priority, Level} + +

Sets the priority of the new process. Equivalent to + executing + process_flag(priority, Level) 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 + process_flag(priority, Level).

+ + {fullsweep_after, Number} + +

This option is only useful for performance tuning. + In general, you should not use this option unless you + know that there is problem with execution times and/or + memory consumption, and you should measure to make sure + that the option improved matters. +

+

The Erlang runtime system uses a generational garbage + collection scheme, using an "old heap" for data that has + survived at least one garbage collection. When there is + no more room on the old heap, a fullsweep garbage + collection will be done.

+

The fullsweep_after option makes it possible to + specify the maximum number of generational collections + before forcing a fullsweep even if there is still room on + the old heap. Setting the number to zero effectively + disables the general collection algorithm, meaning that + all live data is copied at every garbage collection.

+

Here are a few cases when it could be useful to change + fullsweep_after. Firstly, if binaries that are no + longer used should be thrown away as soon as possible. + (Set Number 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 + Number 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 Number to zero. (The value may be set + globally, see + erlang:system_flag/2.)

+ + {min_heap_size, Size} + +

This option is only useful for performance tuning. + In general, you should not use this option unless you + know that there is problem with execution times and/or + memory consumption, and you should measure to make sure + that the option improved matters. +

+

Gives a minimum heap size in words. Setting this value + higher than the system default might speed up some + processes because less garbage collection is done. + Setting too high value, however, might waste memory and + 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 Size values.

+ + + + + + spawn_opt(Node, Module, Function, Args, [Option]) -> pid() + Create a new process with a function as entry point on a given node + + Node = node() + Module = Function = atom() + Args = [term()] + Option = link | {priority, Level} | {fullsweep_after, Number} | {min_heap_size, Size} +  Level = low | normal | high +  Number = int() +  Size = int() + + +

Returns the pid of a new process started by the application + of Module:Function to Args on Node. If + Node does not exist, a useless pid is returned. + Otherwise works like + spawn_opt/4.

+ + + + split_binary(Bin, Pos) -> {Bin1, Bin2} + Split a binary into two + + Bin = Bin1 = Bin2 = binary() + Pos = 1..byte_size(Bin) + + +

Returns a tuple containing the binaries which are the result + of splitting Bin into two parts at position Pos. + This is not a destructive operation. After the operation, + there will be three binaries altogether.

+ 
+> B = list_to_binary("0123456789").
+<<"0123456789">>
+> byte_size(B).
+10
+> {B1, B2} = split_binary(B,3).
+{<<"012">>,<<"3456789">>}
+> byte_size(B1).
+3
+> byte_size(B2).
+7
+ + + + erlang:start_timer(Time, Dest, Msg) -> TimerRef + Start a timer + + Time = int() +  0 <= Time <= 4294967295 + Dest = LocalPid | RegName +  LocalPid = pid() (of a process, alive or dead, on the local node) +  RegName = atom() + Msg = term() + TimerRef = ref() + + +

Starts a timer which will send the message + {timeout, TimerRef, Msg} to Dest + after Time milliseconds.

+

If Dest is an atom, it is supposed to be the name of + a registered process. The process referred to by the name is + looked up at the time of delivery. No error is given if + the name does not refer to a process.

+

If Dest is a pid, the timer will be automatically + canceled if the process referred to by the pid is not alive, + or when the process exits. This feature was introduced in + erts version 5.4.11. Note that timers will not be + automatically canceled when Dest is an atom.

+

See also + erlang:send_after/3, + erlang:cancel_timer/1, + and + erlang:read_timer/1.

+

Failure: badarg if the arguments does not satisfy + the requirements specified above.

+ + + + statistics(Type) -> Res + Information about the system + + Type, Res -- see below + + +

Returns information about the system as specified by + Type:

+ + context_switches + +

Returns {ContextSwitches, 0}, where + ContextSwitches is the total number of context + switches since the system started.

+ + exact_reductions + + +

Returns + {Total_Exact_Reductions, Exact_Reductions_Since_Last_Call}.

+

NOTE:statistics(exact_reductions) is + a more expensive operation than + statistics(reductions) + especially on an Erlang machine with SMP support.

+ + garbage_collection + +

Returns {Number_of_GCs, Words_Reclaimed, 0}. This + information may not be valid for all implementations.

+ + io + +

Returns {{input, Input}, {output, Output}}, + where Input is the total number of bytes received + through ports, and Output is the total number of + bytes output to ports.

+ + reductions + + +

Returns + {Total_Reductions, Reductions_Since_Last_Call}.

+

NOTE: From erts version 5.5 (OTP release R11B) + this value does not include reductions performed in current + time slices of currently scheduled processes. If an + exact value is wanted, use + statistics(exact_reductions).

+ + run_queue + +

Returns the length of the run queue, that is, the number + of processes that are ready to run.

+ + runtime + +

Returns {Total_Run_Time, Time_Since_Last_Call}. + Note that the run-time is the sum of the run-time for all + threads in the Erlang run-time system and may therefore be greater + than the wall-clock time.

+ + wall_clock + +

Returns + {Total_Wallclock_Time, Wallclock_Time_Since_Last_Call}. + wall_clock can be used in the same manner as + runtime, except that real time is measured as + opposed to runtime or CPU time.

+ + +

All times are in milliseconds.

+ 
+> statistics(runtime).
+{1690,1620}
+> statistics(reductions).
+{2046,11}
+> statistics(garbage_collection).
+{85,23961,0}
+ + + + erlang:suspend_process(Suspendee, OptList) -> true | false + Suspend a process + + Suspendee = pid() + OptList = [Opt] + Opt = atom() + + +

Increases the suspend count on the process identified by + Suspendee and puts it in the suspended state if it isn't + already in the suspended state. A suspended process will not be + scheduled for execution until the process has been resumed. +

+ +

A process can be suspended by multiple processes and can + be suspended multiple times by a single process. A suspended + process will not leave the suspended state until its suspend + count reach zero. The suspend count of Suspendee is + decreased when + erlang:resume_process(Suspendee) + is called by the same process that called + erlang:suspend_process(Suspendee). All increased suspend + counts on other processes acquired by a process will automatically be + decreased when the process terminates.

+ +

Currently the following options (Opts) are available:

+ + asynchronous + + A suspend request is sent to the process identified by + Suspendee. Suspendee will eventually suspend + unless it is resumed before it was able to suspend. The caller + of erlang:suspend_process/2 will return immediately, + regardless of whether the Suspendee has suspended yet + or not. Note that the point in time when the Suspendee + will actually suspend cannot be deduced from other events + in the system. The only guarantee given is that the + Suspendee will eventually suspend (unless it + is resumed). If the asynchronous option has not + been passed, the caller of erlang:suspend_process/2 will + be blocked until the Suspendee has actually suspended. + + unless_suspending + + The process identified by Suspendee will be suspended + unless the calling process already is suspending the + Suspendee. If unless_suspending is combined + with the asynchronous option, a suspend request will be + sent unless the calling process already is suspending the + Suspendee or if a suspend request already has been sent + and is in transit. If the calling process already is suspending + the Suspendee, or if combined with the asynchronous + option and a send request already is in transit, + false is returned and the suspend count on Suspendee + will remain unchanged. + + + +

If the suspend count on the process identified by + Suspendee was increased, true is returned; otherwise, + false is returned.

+ + +

This BIF is intended for debugging only.

+ +

Failures:

+ + badarg + + If Suspendee isn't a process identifier. + + badarg + + If the process identified by Suspendee is same the process as + the process calling erlang:suspend_process/2. + + badarg + + If the process identified by Suspendee is not alive. + + badarg + + If the process identified by Suspendee resides on another node. + + badarg + + If OptList isn't a proper list of valid Opts. + + system_limit + + If the process identified by Suspendee has been suspended more + times by the calling process than can be represented by the + currently used internal data structures. The current system limit + is larger than 2 000 000 000 suspends, and it will never be less + than that. + + + + + + erlang:suspend_process(Suspendee) -> true + Suspend a process + + Suspendee = pid() + + +

Suspends the process identified by Suspendee. The + same as calling + erlang:suspend_process(Suspendee, []). For more information see the documentation of erlang:suspend_process/2. +

+ +

This BIF is intended for debugging only.

+ + + + + erlang:system_flag(Flag, Value) -> OldValue + Set system flags + + Flag, Value, OldValue -- see below + + +

Sets various system properties of the Erlang node. Returns + the old value of the flag.

+ + erlang:system_flag(backtrace_depth, Depth) + +

Sets the maximum depth of call stack back-traces in the + exit reason element of 'EXIT' tuples.

+ + erlang:system_flag(cpu_topology, CpuTopology) + + +

Sets the user defined CpuTopology. The user defined + CPU topology will override any automatically detected + CPU topology. By passing undefined as CpuTopology + the system will revert back to the CPU topology automatically + detected. The returned value equals the value returned + from erlang:system_info(cpu_topology) before the + change was made. +

+

The CPU topology is used when binding schedulers to logical + processors. If schedulers are already bound when the CPU + topology is changed, the schedulers will be sent a request + to rebind according to the new CPU topology. +

+

The user defined CPU topology can also be set by passing + the +sct command + line argument to erl. +

+

For information on the CpuTopology type + and more, see the documentation of + erlang:system_info(cpu_topology), + the erl +sct + emulator flag, and + erlang:system_flag(scheduler_bind_type, How). +

+ + erlang:system_flag(fullsweep_after, Number) + +

Number is a non-negative integer which indicates + how many times generational garbage collections can be + done without forcing a fullsweep collection. The value + applies to new processes; processes already running are + not affected.

+

In low-memory systems (especially without virtual + memory), setting the value to 0 can help to conserve + memory.

+

An alternative way to set this value is through the + (operating system) environment variable + ERL_FULLSWEEP_AFTER.

+ + erlang:system_flag(min_heap_size, MinHeapSize) + +

Sets the default minimum heap size for processes. The + size is given in words. The new min_heap_size only + effects processes spawned after the change of + min_heap_size has been made. + The min_heap_size can be set for individual + processes by use of + spawn_opt/N or + process_flag/2.

+ + erlang:system_flag(multi_scheduling, BlockState) + + +

BlockState = block | unblock

+

If multi-scheduling is enabled, more than one scheduler + thread is used by the emulator. Multi-scheduling can be + blocked. When multi-scheduling has been blocked, only + one scheduler thread will schedule Erlang processes.

+

If BlockState =:= block, multi-scheduling will + be blocked. If BlockState =:= unblock and no-one + else is blocking multi-scheduling and this process has + only blocked one time, multi-scheduling will be unblocked. + One process can block multi-scheduling multiple times. + If a process has blocked multiple times, it has to + unblock exactly as many times as it has blocked before it + has released its multi-scheduling block. If a process that + has blocked multi-scheduling exits, it will release its + blocking of multi-scheduling.

+

The return values are disabled, blocked, + or enabled. The returned value describes the + state just after the call to + erlang:system_flag(multi_scheduling, BlockState) + has been made. The return values are described in the + documentation of erlang:system_info(multi_scheduling).

+

NOTE: Blocking of multi-scheduling should normally + not be needed. If you feel that you need to + block multi-scheduling, think through the + problem at least a couple of times again. + Blocking multi-scheduling should only be used + as a last resort since it will most likely be + a very inefficient way to solve the + problem.

+

See also erlang:system_info(multi_scheduling), + erlang:system_info(multi_scheduling_blockers), and + erlang:system_info(schedulers).

+ + erlang:system_flag(scheduler_bind_type, How) + + +

Controls if and how schedulers are bound to logical + processors.

+

When erlang:system_flag(scheduler_bind_type, How) is + called, an asynchronous signal is sent to all schedulers + online which causes them to try to bind or unbind as requested. + NOTE: If a scheduler fails to bind, this + will often be silently ignored. This since it isn't always + possible to verify valid logical processor identifiers. If + an error is reported, it will be reported to the + error_logger. If you want to verify that the + schedulers actually have bound as requested, call + erlang:system_info(scheduler_bindings). +

+

Schedulers can currently only be bound on newer Linux + and Solaris systems, but more systems will be supported + in the future. +

+

In order for the runtime system to be able to bind schedulers, + the CPU topology needs to be known. If the runtime system fails + to automatically detect the CPU topology, it can be defined. + For more information on how to define the CPU topology, see + erlang:system_flag(cpu_topology, CpuTopology). +

+

NOTE: 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.

+

Schedulers can be bound in different ways. The How + argument determines how schedulers are bound. How can + currently be one of:

+ + unbound + +

Schedulers will not be bound to logical processors, i.e., + the operating system decides where the scheduler threads + execute, and when to migrate them. This is the default.

+ + no_spread + +

Schedulers with close scheduler identifiers will be bound + as close as possible in hardware.

+ + thread_spread + +

Thread refers to hardware threads (e.g. Intels + hyper-threads). Schedulers with low scheduler identifiers, + will be bound to the first hardware thread of each core, + then schedulers with higher scheduler identifiers will be + bound to the second hardware thread of each core, etc.

+ + processor_spread + +

Schedulers will be spread like thread_spread, but + also over physical processor chips.

+ + spread + +

Schedulers will be spread as much as possible.

+ + no_node_thread_spread + +

Like thread_spread, but if multiple NUMA + (Non-Uniform Memory Access) nodes exists, + schedulers will be spread over one NUMA node at a time, + i.e., all logical processors of one NUMA node will + be bound to schedulers in sequence.

+ + no_node_processor_spread + +

Like processor_spread, but if multiple NUMA + nodes exists, schedulers will be spread over one + NUMA node at a time, i.e., all logical processors of + one NUMA node will be bound to schedulers in sequence.

+ + thread_no_node_processor_spread + +

A combination of thread_spread, and + no_node_processor_spread. Schedulers will be + spread over hardware threads across NUMA nodes, but + schedulers will only be spread over processors internally + in one NUMA node at a time.

+ + default_bind + +

Binds schedulers the default way. Currently the default + is thread_no_node_processor_spread (which might change + in the future).

+ + +

How schedulers are bound matters. For example, in + situations when there are fewer running processes than + schedulers online, the runtime system tries to migrate + processes to schedulers with low scheduler identifiers. + The more the schedulers are spread over the hardware, + the more resources will be available to the runtime + system in such situations. +

+

The value returned equals How before the + scheduler_bind_type flag was changed.

+

Failure:

+ + notsup + +

If binding of schedulers is not supported.

+ + badarg + +

If How isn't one of the documented alternatives.

+ + badarg + +

If no CPU topology information is available.

+ + +

The scheduler bind type can also be set by passing + the +sbt command + line argument to erl. +

+

For more information, see + erlang:system_info(scheduler_bind_type), + erlang:system_info(scheduler_bindings), + the erl +sbt + emulator flag, and + erlang:system_flag(cpu_topology, CpuTopology). +

+ + erlang:system_flag(schedulers_online, SchedulersOnline) + + +

Sets the amount of schedulers online. Valid range is + . +

+

For more information see, + erlang:system_info(schedulers), + and + erlang:system_info(schedulers_online). +

+ + erlang:system_flag(trace_control_word, TCW) + +

Sets the value of the node's trace control word to + TCW. TCW should be an unsigned integer. For + more information see documentation of the + set_tcw + function in the match specification documentation in the + ERTS User's Guide.

+ + + +

The schedulers option has been removed as + of erts version 5.5.3. The number of scheduler + threads is determined at emulator boot time, and + cannot be changed after that.

+ + + + + erlang:system_info(Type) -> Res + Information about the system + + Type, Res -- see below + + +

Returns various information about the current system + (emulator) as specified by Type:

+ + allocated_areas + + +

Returns a list of tuples with information about + miscellaneous allocated memory areas.

+

Each tuple contains an atom describing type of memory as + first element and amount of allocated memory in bytes as + second element. In those cases when there is information + present about allocated and used memory, a third element + is present. This third element contains the amount of + used memory in bytes.

+

erlang:system_info(allocated_areas) is intended + for debugging, and the content is highly implementation + dependent. The content of the results will therefore + change when needed without prior notice.

+

Note: The sum of these values is not + the total amount of memory allocated by the emulator. + Some values are part of other values, and some memory + areas are not part of the result. If you are interested + in the total amount of memory allocated by the emulator + see erlang:memory/0,1.

+ + allocator + + +

Returns {Allocator, Version, Features, Settings}.

+

Types:

+ + Allocator = undefined | elib_malloc | glibc + Version = [int()] + Features = [atom()] + Settings = [{Subsystem, [{Parameter, Value}]}] + Subsystem = atom() + Parameter = atom() + Value = term() + +

Explanation:

+ + +

Allocator corresponds to the malloc() + implementation used. If Allocator equals + undefined, the malloc() implementation + used could not be identified. Currently + elib_malloc and glibc can be identified.

+ + +

Version is a list of integers (but not a + string) representing the version of + the malloc() implementation used.

+ + +

Features is a list of atoms representing + allocation features used.

+ + +

Settings is a list of subsystems, their + configurable parameters, and used values. Settings + may differ between different combinations of + platforms, allocators, and allocation features. + Memory sizes are given in bytes.

+ + +

See also "System Flags Effecting erts_alloc" in + erts_alloc(3).

+ + alloc_util_allocators + + +

Returns a list of the names of all allocators + using the ERTS internal alloc_util framework + as atoms. For more information see the + "the + alloc_util framework" section in the + erts_alloc(3) documentation. +

+ + {allocator, Alloc} + + +

Returns information about the specified allocator. + As of erts version 5.6.1 the return value is a list + of {instance, InstanceNo, InstanceInfo} tuples + where InstanceInfo contains information about + a specific instance of the allocator. + If Alloc is not a recognized allocator, + undefined is returned. If Alloc is disabled, + false is returned.

+

Note: The information returned is highly + implementation dependent and may be changed, or removed + at any time without prior notice. It was initially + intended as a tool when developing new allocators, but + since it might be of interest for others it has been + briefly documented.

+

The recognized allocators are listed in + erts_alloc(3). + After reading the erts_alloc(3) documentation, + the returned information + should more or less speak for itself. But it can be worth + explaining some things. Call counts are presented by two + values. The first value is giga calls, and the second + value is calls. mbcs, and sbcs are + abbreviations for, respectively, multi-block carriers, and + single-block carriers. Sizes are presented in bytes. When + it is not a size that is presented, it is the amount of + something. Sizes and amounts are often presented by three + values, the first is current value, the second is maximum + value since the last call to + erlang:system_info({allocator, Alloc}), and + the third is maximum value since the emulator was started. + If only one value is present, it is the current value. + fix_alloc memory block types are presented by two + values. The first value is memory pool size and + the second value used memory size.

+ + {allocator_sizes, Alloc} + + +

Returns various size information for the specified + allocator. The information returned is a subset of the + information returned by + erlang:system_info({allocator, Alloc}). +

+ + c_compiler_used + +

Returns a two-tuple describing the C compiler used when + compiling the runtime system. The first element is an + atom describing the name of the compiler, or undefined + if unknown. The second element is a term describing the + version of the compiler, or undefined if unknown. +

+ + check_io + +

Returns a list containing miscellaneous information + regarding the emulators internal I/O checking. Note, + the content of the returned list may vary between + platforms and over time. The only thing guaranteed is + that a list is returned.

+ + compat_rel + +

Returns the compatibility mode of the local node as + an integer. The integer returned represents the + Erlang/OTP release which the current emulator has been + set to be backward compatible with. The compatibility + mode can be configured at startup by using the command + line flag +R, see + erl(1).

+ + cpu_topology + + +

Returns the CpuTopology which currently is used by the + emulator. The CPU topology is used when binding schedulers + to logical processors. The CPU topology used is the user defined + CPU topology if such exist; otherwise, the automatically + detected CPU topology if such exist. If no CPU topology + exist undefined is returned.

+

Types:

+ + CpuTopology = LevelEntryList | undefined + LevelEntryList = [LevelEntry] (all + LevelEntrys of a LevelEntryList + must contain the same LevelTag, except + on the top level where both node and + processor LevelTags may co-exist) + LevelEntry = {LevelTag, SubLevel} + | {LevelTag, InfoList, SubLevel} + ({LevelTag, SubLevel} + == {LevelTag, [], SubLevel}) + LevelTag = node|processor|core|thread + (more LevelTags may be introduced in + the future) + SubLevel = [LevelEntry] | LogicalCpuId + LogicalCpuId = {logical, integer()} + InfoList = [] (the InfoList + may be extended in the future) + +

node refers to NUMA (non-uniform memory access) + nodes, and thread refers to hardware threads + (e.g. Intels hyper-threads).

+

A level in the CpuTopology term can be omitted if + only one entry exists and the InfoList is empty. +

+

thread can only be a sub level to core. + core can be a sub level to either processor + or node. processor can either be on the + top level or a sub level to node. node + can either be on the top level or a sub level to + processor. That is, NUMA nodes can be processor + internal or processor external. A CPU topology can + consist of a mix of processor internal and external + NUMA nodes, as long as each logical CPU belongs to one + and only one NUMA node. Cache hierarchy is not part of + the CpuTopology type yet, but will be in the + future. Other things may also make it into the CPU + topology in the future. In other words, expect the + CpuTopology type to change. +

+ + {cpu_topology, defined} + +

Returns the user defined CpuTopology. For more + information see the documentation of + erlang:system_flag(cpu_topology, CpuTopology) + and the documentation of the + cpu_topology + argument. +

+ + {cpu_topology, detected} + +

Returns the automatically detected CpuTopology. The + emulator currently only detects the CPU topology on some newer + linux and solaris systems. For more information see the + documentation of the + cpu_topology + argument. +

+ + {cpu_topology, used} + +

Returns the CpuTopology which is used by the + emulator. For more information see the + documentation of the + cpu_topology + argument. +

+ + creation + +

Returns the creation of the local node as an integer. + The creation is changed when a node is restarted. The + creation of a node is stored in process identifiers, port + identifiers, and references. This makes it (to some + extent) possible to distinguish between identifiers from + different incarnations of a node. Currently valid + creations are integers in the range 1..3, but this may + (probably will) change in the future. If the node is not + alive, 0 is returned.

+ + debug_compiled + +

Returns true if the emulator has been debug + compiled; otherwise, false. +

+ + dist + +

Returns a binary containing a string of distribution + information formatted as in Erlang crash dumps. For more + information see the "How to interpret the Erlang crash dumps" + chapter in the ERTS User's Guide.

+ + dist_ctrl + +

Returns a list of tuples + {Node, ControllingEntity}, one entry for each + connected remote node. The Node is the name of the + node and the ControllingEntity is the port or pid + responsible for the communication to that node. More + specifically, the ControllingEntity for nodes + connected via TCP/IP (the normal case) is the socket + actually used in communication with the specific node.

+ + driver_version + +

Returns a string containing the erlang driver version + used by the runtime system. It will be on the form + "<major ver>.<minor ver>".

+ + elib_malloc + +

If the emulator uses the elib_malloc memory + allocator, a list of two-element tuples containing status + information is returned; otherwise, false is + returned. The list currently contains the following + two-element tuples (all sizes are presented in bytes):

+ + {heap_size, Size} + +

Where Size is the current heap size.

+ + {max_alloced_size, Size} + +

Where Size is the maximum amount of memory + allocated on the heap since the emulator started.

+ + {alloced_size, Size} + +

Where Size is the current amount of memory + allocated on the heap.

+ + {free_size, Size} + +

Where Size is the current amount of free + memory on the heap.

+ + {no_alloced_blocks, No} + +

Where No is the current number of allocated + blocks on the heap.

+ + {no_free_blocks, No} + +

Where No is the current number of free blocks + on the heap.

+ + {smallest_alloced_block, Size} + +

Where Size is the size of the smallest + allocated block on the heap.

+ + {largest_free_block, Size} + +

Where Size is the size of the largest free + block on the heap.

+ + + + fullsweep_after + +

Returns {fullsweep_after, int()} which is the + fullsweep_after garbage collection setting used + by default. For more information see + garbage_collection described below.

+ + garbage_collection + +

Returns a list describing the default garbage collection + settings. A process spawned on the local node by a + spawn or spawn_link will use these + garbage collection settings. The default settings can be + changed by use of + system_flag/2. + spawn_opt/4 + can spawn a process that does not use the default + settings.

+ + global_heaps_size + +

Returns the current size of the shared (global) heap.

+ + heap_sizes + +

Returns a list of integers representing valid heap sizes + in words. All Erlang heaps are sized from sizes in this + list.

+ + heap_type + +

Returns the heap type used by the current emulator. + Currently the following heap types exist:

+ + private + +

Each process has a heap reserved for its use and no + references between heaps of different processes are + allowed. Messages passed between processes are copied + between heaps.

+ + shared + +

One heap for use by all processes. Messages passed + between processes are passed by reference.

+ + hybrid + +

A hybrid of the private and shared heap + types. A shared heap as well as private heaps are + used.

+ + + + info + +

Returns a binary containing a string of miscellaneous + system information formatted as in Erlang crash dumps. + For more information see the + "How to interpret the Erlang crash dumps" chapter in the ERTS + User's Guide.

+ + kernel_poll + +

Returns true if the emulator uses some kind of + kernel-poll implementation; otherwise, false.

+ + loaded + +

Returns a binary containing a string of loaded module + information formatted as in Erlang crash dumps. For more + information see the "How to interpret the Erlang crash dumps" chapter + in the ERTS User's Guide.

+ + logical_processors + +

Returns the number of logical processors detected on the + system as an integer or the atom unknown if the + emulator wasn't able to detect any. +

+ + machine + +

Returns a string containing the Erlang machine name.

+ + modified_timing_level + +

Returns the modified timing level (an integer) if + modified timing has been enabled; otherwise, + undefined. See the +T command line flag + in the documentation of the + erl(1) + command for more information on modified timing.

+ + multi_scheduling + + +

Returns disabled, blocked, or enabled. + A description of the return values:

+ + disabled + +

The emulator has only one scheduler thread. The + emulator does not have SMP support, or have been + started with only one scheduler thread.

+ + blocked + +

The emulator has more than one scheduler thread, + but all scheduler threads but one have been blocked, + i.e., only one scheduler thread will schedule + Erlang processes and execute Erlang code.

+ + enabled + +

The emulator has more than one scheduler thread, + and no scheduler threads have been blocked, i.e., + all available scheduler threads will schedule + Erlang processes and execute Erlang code.

+ + +

See also erlang:system_flag(multi_scheduling, BlockState), + erlang:system_info(multi_scheduling_blockers), and + erlang:system_info(schedulers).

+ + multi_scheduling_blockers + + +

Returns a list of PIDs when multi-scheduling + is blocked; otherwise, the empty list. The PIDs + in the list is PIDs of the processes currently + blocking multi-scheduling. A PID will only be + present once in the list, even if the corresponding + process has blocked multiple times.

+

See also erlang:system_flag(multi_scheduling, BlockState), + erlang:system_info(multi_scheduling), and + erlang:system_info(schedulers).

+ + otp_release + + +

Returns a string containing the OTP release number.

+ + process_count + +

Returns the number of processes currently existing at + the local node as an integer. The same value as + length(processes()) returns.

+ + process_limit + +

Returns the maximum number of concurrently existing + processes at the local node as an integer. This limit + can be configured at startup by using the command line + flag +P, see + erl(1).

+ + procs + +

Returns a binary containing a string of process and port + information formatted as in Erlang crash dumps. For more + information see the "How to interpret the Erlang crash dumps" chapter + in the ERTS User's Guide.

+ + scheduler_bind_type + + +

Returns information on how user has requested + schedulers to be bound or not bound.

+

NOTE: Even though user has requested + schedulers to be bound via + erlang:system_flag(scheduler_bind_type, How), + they might have silently failed to bind. In order to + inspect actual scheduler bindings call + erlang:system_info(scheduler_bindings). +

+

For more information, see + erlang:system_flag(scheduler_bind_type, How), and + erlang:system_info(scheduler_bindings). +

+ + scheduler_bindings + + +

Returns information on currently used scheduler + bindings.

+

A tuple of a size equal to + erlang:system_info(schedulers) is returned. The elements of the tuple are integers + or the atom unbound. Logical processor identifiers + are represented as integers. The Nth + element of the tuple equals the current binding for + the scheduler with the scheduler identifier equal to + N. E.g., if the schedulers have been bound, + element(erlang:system_info(scheduler_id), + erlang:system_info(scheduler_bindings)) will return + the identifier of the logical processor that the calling + process is executing on. +

+

Note that only schedulers online can be bound to logical + processors.

+

For more information, see + erlang:system_flag(scheduler_bind_type, How), + erlang:system_info(schedulers_online). +

+ + scheduler_id + + +

Returns the scheduler id (SchedulerId) of the + scheduler thread that the calling process is executing + on. SchedulerId is a positive integer; where + . See also + erlang:system_info(schedulers).

+ + schedulers + + +

Returns the number of scheduler threads used by + the emulator. Scheduler threads online schedules Erlang + processes and Erlang ports, and execute Erlang code + and Erlang linked in driver code.

+

The number of scheduler threads is determined at + emulator boot time and cannot be changed after + that. The amount of schedulers online can + however be changed at any time.

+

See also erlang:system_flag(schedulers_online, SchedulersOnline), + erlang:system_info(schedulers_online), + erlang:system_info(scheduler_id), + erlang:system_flag(multi_scheduling, BlockState), + erlang:system_info(multi_scheduling), and + and erlang:system_info(multi_scheduling_blockers).

+ + schedulers_online + + +

Returns the amount of schedulers online. The scheduler + identifiers of schedulers online satisfy the following + relationship: + . +

+

For more information, see + erlang:system_info(schedulers), + and + erlang:system_flag(schedulers_online, SchedulersOnline). +

+ + smp_support + +

Returns true if the emulator has been compiled + with smp support; otherwise, false.

+ + system_version + +

Returns a string containing version number and + some important properties such as the number of schedulers.

+ + system_architecture + +

Returns a string containing the processor and OS + architecture the emulator is built for.

+ + threads + +

Returns true if the emulator has been compiled + with thread support; otherwise, false is + returned.

+ + thread_pool_size + + +

Returns the number of async threads in the async thread + pool used for asynchronous driver calls + (driver_async()) + as an integer.

+ + trace_control_word + +

Returns the value of the node's trace control word. + For more information see documentation of the function + get_tcw in "Match Specifications in Erlang", + ERTS User's Guide.

+ + version + + +

Returns a string containing the version number of the + emulator.

+ + wordsize + +

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.

+ + + +

The scheduler argument has changed name to + scheduler_id. This in order to avoid mixup with + the schedulers argument. The scheduler + argument was introduced in ERTS version 5.5 and renamed + in ERTS version 5.5.1.

+ + + + + + erlang:system_monitor() -> MonSettings + Current system performance monitoring settings + + MonSettings -> {MonitorPid, Options} | undefined +  MonitorPid = pid() +  Options = [Option] +   Option = {long_gc, Time} | {large_heap, Size} | busy_port | busy_dist_port +    Time = Size = int() + + +

Returns the current system monitoring settings set by + erlang:system_monitor/2 + as {MonitorPid, Options}, or undefined if there + are no settings. The order of the options may be different + from the one that was set.

+ + + + + erlang:system_monitor(undefined | {MonitorPid, Options}) -> MonSettings + Set or clear system performance monitoring options + + MonitorPid, Options, MonSettings -- see below + + +

When called with the argument undefined, all + system performance monitoring settings are cleared.

+

Calling the function with {MonitorPid, Options} as + argument, is the same as calling + erlang:system_monitor(MonitorPid, Options).

+

Returns the previous system monitor settings just like + erlang:system_monitor/0.

+ + + + + erlang:system_monitor(MonitorPid, [Option]) -> MonSettings + Set system performance monitoring options + + MonitorPid = pid() + Option = {long_gc, Time} | {large_heap, Size} | busy_port | busy_dist_port +  Time = Size = int() + MonSettings = {OldMonitorPid, [Option]} +  OldMonitorPid = pid() + + +

Sets system performance monitoring options. MonitorPid + is a local pid that will receive system monitor messages, and + the second argument is a list of monitoring options:

+ + {long_gc, Time} + +

If a garbage collection in the system takes at least + Time wallclock milliseconds, a message + {monitor, GcPid, long_gc, Info} is sent to + MonitorPid. GcPid is the pid that was + garbage collected and Info is a list of two-element + tuples describing the result of the garbage collection. + One of the tuples is {timeout, GcTime} where + GcTime is the actual time for the garbage + collection in milliseconds. The other tuples are + tagged with heap_size, heap_block_size, + stack_size, mbuf_size, old_heap_size, + and old_heap_block_size. These tuples are + explained in the documentation of the + gc_start + trace message (see + erlang:trace/3). + New tuples may be added, and the order of the tuples in + the Info list may be changed at any time without prior + notice. +

+ + {large_heap, Size} + +

If a garbage collection in the system results in + the allocated size of a heap being at least Size + words, a message {monitor, GcPid, large_heap, Info} + is sent to MonitorPid. GcPid and Info + are the same as for long_gc above, except that + the tuple tagged with timeout is not present. + Note: As of erts version 5.6 the monitor message + is sent if the sum of the sizes of all memory blocks allocated + for all heap generations is equal to or larger than Size. + Previously the monitor message was sent if the memory block + allocated for the youngest generation was equal to or larger + than Size. +

+ + busy_port + +

If a process in the system gets suspended because it + sends to a busy port, a message + {monitor, SusPid, busy_port, Port} is sent to + MonitorPid. SusPid is the pid that got + suspended when sending to Port.

+ + busy_dist_port + +

If a process in the system gets suspended because it + sends to a process on a remote node whose inter-node + communication was handled by a busy port, a message + {monitor, SusPid, busy_dist_port, Port} is sent to + MonitorPid. SusPid is the pid that got + suspended when sending through the inter-node + communication port Port.

+ + +

Returns the previous system monitor settings just like + erlang:system_monitor/0.

+ +

If a monitoring process gets so large that it itself + starts to cause system monitor messages when garbage + collecting, the messages will enlarge the process's + message queue and probably make the problem worse.

+

Keep the monitoring process neat and do not set the system + monitor limits too tight.

+ +

Failure: badarg if MonitorPid does not exist.

+ + + + + erlang:system_profile() -> ProfilerSettings + Current system profiling settings + + ProfilerSettings -> {ProfilerPid, Options} | undefined +  ProfilerPid = pid() | port() +  Options = [Option] +   Option = runnable_procs | runnable_ports | scheduler | exclusive + + +

Returns the current system profiling settings set by + erlang:system_profile/2 + as {ProfilerPid, Options}, or undefined if there + are no settings. The order of the options may be different + from the one that was set.

+ + + + + erlang:system_profile(ProfilerPid, Options) -> ProfilerSettings + Current system profiling settings + + ProfilerSettings -> {ProfilerPid, Options} | undefined +  ProfilerPid = pid() | port() +  Options = [Option] +   Option = runnable_procs | runnable_ports | scheduler | exclusive + + +

Sets system profiler options. ProfilerPid + is a local pid or port that will receive profiling messages. The + receiver is excluded from all profiling. + The second argument is a list of profiling options:

+ + runnable_procs + +

If a process is put into or removed from the run queue a message, + {profile, Pid, State, Mfa, Ts}, is sent to + ProfilerPid. Running processes that is reinserted into the + run queue after having been preemptively scheduled out will not trigger this + message. +

+ + runnable_ports + +

If a port is put into or removed from the run queue a message, + {profile, Port, State, 0, Ts}, is sent to + ProfilerPid. +

+ + scheduler + +

If a scheduler is put to sleep or awoken a message, + {profile, scheduler, Id, State, NoScheds, Ts}, is sent + to ProfilerPid. +

+ + exclusive + +

+ If a synchronous call to a port from a process is done, the + calling process is considered not runnable during the call + runtime to the port. The calling process is notified as + inactive and subsequently active when the port + callback returns. +

+ + +

erlang:system_profile is considered experimental and + its behaviour may change in the future.

+ + + + + + term_to_binary(Term) -> ext_binary() + Encode a term to an Erlang external term format binary + + Term = term() + + +

Returns a binary data object which is the result of encoding + Term according to the Erlang external term format.

+

This can be used for a variety of purposes, for example + writing a term to a file in an efficient way, or sending an + Erlang term to some type of communications channel not + supported by distributed Erlang.

+

See also + binary_to_term/1.

+ + + + term_to_binary(Term, [Option]) -> ext_binary() + Encode a term to en Erlang external term format binary + + Term = term() + Option = compressed | {compressed,Level} | {minor_version,Version} + + +

Returns a binary data object which is the result of encoding + Term according to the Erlang external term format.

+

If the option compressed is provided, the external + term format will be compressed. The compressed format is + automatically recognized by binary_to_term/1 in R7B and later.

+

It is also possible to specify a compression level by giving + the option {compressed,Level}, where Level is an + integer from 0 through 9. 0 means that no compression + will be done (it is the same as not giving any compressed option); + 1 will take the least time but may not compress as well as + the higher levels; 9 will take the most time and may produce + a smaller result. Note the "mays" in the preceding sentence; depending + on the input term, level 9 compression may or may not produce a smaller + result than level 1 compression.

+

Currently, compressed gives the same result as + {compressed,6}.

+

The option {minor_version,Version} can be use to control + some details of the encoding. This option was + introduced in R11B-4. Currently, the allowed values for Version + are 0 and 1.

+

{minor_version,1} forces any floats in the term to be encoded + in a more space-efficient and exact way (namely in the 64-bit IEEE format, + rather than converted to a textual representation). binary_to_term/1 + in R11B-4 and later is able decode the new representation.

+

{minor_version,0} is currently the default, meaning that floats + will be encoded using a textual representation; this option is useful if + you want to ensure that releases prior to R11B-4 can decode resulting + binary.

+

See also + binary_to_term/1.

+ + + + throw(Any) + Throw an exception + + Any = term() + + +

A non-local return from a function. If evaluated within a + catch, catch will return the value Any.

+ 
+> catch throw({hello, there}).
+{hello,there}
+

Failure: nocatch if not evaluated within a catch.

+ + + + time() -> {Hour, Minute, Second} + Current time + + Hour = Minute = Second = int() + + +

Returns the current time as {Hour, Minute, Second}.

+

The time zone and daylight saving time correction depend on + the underlying OS.

+ 
+> time().
+{9,42,44}
+ + + + tl(List1) -> List2 + Tail of a list + + List1 = List2 = [term()] + + +

Returns the tail of List1, that is, the list minus + the first element.

+ 
+> tl([geesties, guilies, beasties]).
+[guilies, beasties]
+

Allowed in guard tests.

+

Failure: badarg if List is the empty list [].

+ + + + erlang:trace(PidSpec, How, FlagList) -> int() + Set trace flags for a process or processes + + PidSpec = pid() | existing | new | all + How = bool() + FlagList = [Flag] +  Flag -- see below + + +

Turns on (if How == true) or off (if + How == false) the trace flags in FlagList for + the process or processes represented by PidSpec.

+

PidSpec is either a pid for a local process, or one of + the following atoms:

+ + existing + +

All processes currently existing.

+ + new + +

All processes that will be created in the future.

+ + all + +

All currently existing processes and all processes that + will be created in the future.

+ + +

FlagList can contain any number of the following + flags (the "message tags" refers to the list of messages + following below):

+ + all + +

Set all trace flags except {tracer, Tracer} and + cpu_timestamp that are in their nature different + than the others.

+ + send + +

Trace sending of messages.

+

Message tags: send, + send_to_non_existing_process.

+ + 'receive' + +

Trace receiving of messages.

+

Message tags: 'receive'.

+ + procs + +

Trace process related events.

+

Message tags: spawn, exit, + register, unregister, link, + unlink, getting_linked, + getting_unlinked.

+ + call + +

Trace certain function calls. Specify which function + calls to trace by calling + erlang:trace_pattern/3.

+

Message tags: call, return_from.

+ + silent + +

Used in conjunction with the call trace flag. + The call, return_from and return_to + trace messages are inhibited if this flag is set, + but if there are match specs they are executed as normal.

+

Silent mode is inhibited by executing + erlang:trace(_, false, [silent|_]), + or by a match spec executing the {silent, false} + function.

+

The silent trace flag facilitates setting up + a trace on many or even all processes in the system. + Then the interesting trace can be activated and + deactivated using the {silent,Bool} + match spec function, giving a high degree + of control of which functions with which + arguments that triggers the trace.

+

Message tags: call, return_from, + return_to. Or rather, the absence of.

+ + return_to + +

Used in conjunction with the call trace flag. + Trace the actual return from a traced function back to + its caller. Only works for functions traced with + the local option to + erlang:trace_pattern/3.

+

The semantics is that a trace message is sent when a + call traced function actually returns, that is, when a + chain of tail recursive calls is ended. There will be + only one trace message sent per chain of tail recursive + calls, why the properties of tail recursiveness for + function calls are kept while tracing with this flag. + Using call and return_to trace together + makes it possible to know exactly in which function a + process executes at any time.

+

To get trace messages containing return values from + functions, use the {return_trace} match_spec + action instead.

+

Message tags: return_to.

+ + running + +

Trace scheduling of processes.

+

Message tags: in, and out.

+ + exiting + +

Trace scheduling of an exiting processes.

+

Message tags: in_exiting, out_exiting, and + out_exited.

+ + garbage_collection + +

Trace garbage collections of processes.

+

Message tags: gc_start, gc_end.

+ + timestamp + +

Include a time stamp in all trace messages. The time + stamp (Ts) is of the same form as returned by + erlang:now().

+ + cpu_timestamp + +

A global trace flag for the Erlang node that makes all + trace timestamps be in CPU time, not wallclock. It is + only allowed with PidSpec==all. If the host + machine operating system does not support high resolution + CPU time measurements, trace/3 exits with + badarg.

+ + arity + +

Used in conjunction with the call trace flag. + {M, F, Arity} will be specified instead of + {M, F, Args} in call trace messages.

+ + set_on_spawn + +

Makes any process created by a traced process inherit + its trace flags, including the set_on_spawn flag.

+ + set_on_first_spawn + +

Makes the first process created by a traced process + inherit its trace flags, excluding + the set_on_first_spawn flag.

+ + set_on_link + +

Makes any process linked by a traced process inherit its + trace flags, including the set_on_link flag.

+ + set_on_first_link + +

Makes the first process linked to by a traced process + inherit its trace flags, excluding + the set_on_first_link flag.

+ + {tracer, Tracer} + +

Specify where to send the trace messages. Tracer + must be the pid of a local process or the port identifier + of a local port. If this flag is not given, trace + messages will be sent to the process that called + erlang:trace/3.

+ + +

The effect of combining set_on_first_link with + set_on_link is the same as having + set_on_first_link alone. Likewise for + set_on_spawn and set_on_first_spawn.

+

If the timestamp flag is not given, the tracing + process will receive the trace messages described below. + Pid is the pid of the traced process in which + the traced event has occurred. The third element of the tuple + is the message tag.

+

If the timestamp flag is given, the first element of + the tuple will be trace_ts instead and the timestamp + is added last in the tuple.

+ + {trace, Pid, 'receive', Msg} + +

When Pid receives the message Msg.

+ + {trace, Pid, send, Msg, To} + +

When Pid sends the message Msg to + the process To.

+ + {trace, Pid, send_to_non_existing_process, Msg, To} + +

When Pid sends the message Msg to + the non-existing process To.

+ + {trace, Pid, call, {M, F, Args}} + +

When Pid calls a traced function. The return + values of calls are never supplied, only the call and its + arguments.

+

Note that the trace flag arity can be used to + change the contents of this message, so that Arity + is specified instead of Args.

+ + {trace, Pid, return_to, {M, F, Arity}} + +

When Pid returns to the specified + function. This trace message is sent if both + the call and the return_to flags are set, + and the function is set to be traced on local + function calls. The message is only sent when returning + from a chain of tail recursive function calls where at + least one call generated a call trace message + (that is, the functions match specification matched and + {message, false} was not an action).

+ + {trace, Pid, return_from, {M, F, Arity}, ReturnValue} + +

When Pid returns from the specified + function. This trace message is sent if the call + flag is set, and the function has a match specification + with a return_trace or exception_trace action.

+ + {trace, Pid, exception_from, {M, F, Arity}, {Class, Value}} + +

When Pid exits from the specified + function due to an exception. This trace message is sent + if the call flag is set, and the function has + a match specification with an exception_trace action.

+ + {trace, Pid, spawn, Pid2, {M, F, Args}} + +

When Pid spawns a new process Pid2 with + the specified function call as entry point.

+

Note that Args is supposed to be the argument + list, but may be any term in the case of an erroneous + spawn.

+ + {trace, Pid, exit, Reason} + +

When Pid exits with reason Reason.

+ + {trace, Pid, link, Pid2} + +

When Pid links to a process Pid2.

+ + {trace, Pid, unlink, Pid2} + +

When Pid removes the link from a process + Pid2.

+ + {trace, Pid, getting_linked, Pid2} + +

When Pid gets linked to a process Pid2.

+ + {trace, Pid, getting_unlinked, Pid2} + +

When Pid gets unlinked from a process Pid2.

+ + {trace, Pid, register, RegName} + +

When Pid gets the name RegName registered.

+ + {trace, Pid, unregister, RegName} + +

When Pid gets the name RegName unregistered. + Note that this is done automatically when a registered + process exits.

+ + {trace, Pid, in, {M, F, Arity} | 0} + +

When Pid is scheduled to run. The process will + run in function {M, F, Arity}. On some rare + occasions the current function cannot be determined, then + the last element Arity is 0.

+ + {trace, Pid, out, {M, F, Arity} | 0} + +

When Pid is scheduled out. The process was + running in function {M, F, Arity}. On some rare occasions + the current function cannot be determined, then the last + element Arity is 0.

+ + {trace, Pid, gc_start, Info} + + +

Sent when garbage collection is about to be started. + Info is a list of two-element tuples, where + the first element is a key, and the second is the value. + You should not depend on the tuples have any defined + order. Currently, the following keys are defined:

+ + heap_size + The size of the used part of the heap. + heap_block_size + The size of the memory block used for storing + the heap and the stack. + old_heap_size + The size of the used part of the old heap. + old_heap_block_size + The size of the memory block used for storing + the old heap. + stack_size + The actual size of the stack. + recent_size + The size of the data that survived the previous garbage + collection. + mbuf_size + The combined size of message buffers associated with + the process. + +

All sizes are in words.

+ + {trace, Pid, gc_end, Info} + +

Sent when garbage collection is finished. Info + contains the same kind of list as in the gc_start + message, but the sizes reflect the new sizes after + garbage collection.

+ + +

If the tracing process dies, the flags will be silently + removed.

+

Only one process can trace a particular process. For this + reason, attempts to trace an already traced process will fail.

+

Returns: A number indicating the number of processes that + matched PidSpec. If PidSpec is a pid, + the return value will be 1. If PidSpec is + all or existing the return value will be + the number of processes running, excluding tracer processes. + If PidSpec is new, the return value will be + 0.

+

Failure: If specified arguments are not supported. For + example cpu_timestamp is not supported on all + platforms.

+ + + + erlang:trace_delivered(Tracee) -> Ref + Notification when trace has been delivered + + Tracee = pid() | all + Ref = reference() + + +

The delivery of trace messages is dislocated on the time-line + compared to other events in the system. If you know that the + Tracee has passed some specific point in its execution, + and you want to know when at least all trace messages + corresponding to events up to this point have reached the tracer + you can use erlang:trace_delivered(Tracee). A + {trace_delivered, Tracee, Ref} message is sent to + the caller of erlang:trace_delivered(Tracee) when it + is guaranteed that all trace messages have been delivered to + the tracer up to the point that the Tracee had reached + at the time of the call to + erlang:trace_delivered(Tracee).

+

Note that the trace_delivered message does not + imply that trace messages have been delivered; instead, it implies + that all trace messages that should be delivered have + been delivered. It is not an error if Tracee isn't, and + hasn't been traced by someone, but if this is the case, + no trace messages will have been delivered when the + trace_delivered message arrives.

+

Note that Tracee has to refer to a process currently, + or previously existing on the same node as the caller of + erlang:trace_delivered(Tracee) resides on. + The special Tracee atom all denotes all processes + that currently are traced in the node.

+

An example: Process A is tracee, port B is + tracer, and process C is the port owner of B. + C wants to close B when A exits. C + can ensure that the trace isn't truncated by calling + erlang:trace_delivered(A) when A exits and wait + for the {trace_delivered, A, Ref} message before closing + B.

+

Failure: badarg if Tracee does not refer to a + process (dead or alive) on the same node as the caller of + erlang:trace_delivered(Tracee) resides on.

+ + + + erlang:trace_info(PidOrFunc, Item) -> Res + Trace information about a process or function + + PidOrFunc = pid() | new | {Module, Function, Arity} | on_load +  Module = Function = atom() +  Arity = int() + Item, Res -- see below + + +

Returns trace information about a process or function.

+

To get information about a process, PidOrFunc should + be a pid or the atom new. The atom new means + that the default trace state for processes to be created will + be returned. Item must have one of the following + values:

+ + flags + +

Return a list of atoms indicating what kind of traces is + enabled for the process. The list will be empty if no + traces are enabled, and one or more of the followings + atoms if traces are enabled: send, + 'receive', set_on_spawn, call, + return_to, procs, set_on_first_spawn, + set_on_link, running, + garbage_collection, timestamp, and + arity. The order is arbitrary.

+ + tracer + +

Return the identifier for process or port tracing this + process. If this process is not being traced, the return + value will be [].

+ + +

To get information about a function, PidOrFunc should + be a three-element tuple: {Module, Function, Arity} or + the atom on_load. No wildcards are allowed. Returns + undefined if the function does not exist or + false if the function is not traced at all. Item + must have one of the following values:

+ + traced + +

Return global if this function is traced on + global function calls, local if this function is + traced on local function calls (i.e local and global + function calls), and false if neither local nor + global function calls are traced.

+ + match_spec + +

Return the match specification for this function, if it + has one. If the function is locally or globally traced but + has no match specification defined, the returned value + is [].

+ + meta + +

Return the meta trace tracer process or port for this + function, if it has one. If the function is not meta + traced the returned value is false, and if + the function is meta traced but has once detected that + the tracer proc is invalid, the returned value is [].

+ + meta_match_spec + +

Return the meta trace match specification for this + function, if it has one. If the function is meta traced + but has no match specification defined, the returned + value is [].

+ + call_count + +

Return the call count value for this function or + true for the pseudo function on_load if call + count tracing is active. Return false otherwise. + See also + erlang:trace_pattern/3.

+ + all + +

Return a list containing the {Item, Value} tuples + for all other items, or return false if no tracing + is active for this function.

+ + +

The actual return value will be {Item, Value}, where + Value is the requested information as described above. + If a pid for a dead process was given, or the name of a + non-existing function, Value will be undefined.

+

If PidOrFunc is the on_load, the information + returned refers to the default value for code that will be + loaded.

+ + + + erlang:trace_pattern(MFA, MatchSpec) -> int() + Set trace patterns for global call tracing + +

The same as + erlang:trace_pattern(MFA, MatchSpec, []), + retained for backward compatibility.

+ + + + erlang:trace_pattern(MFA, MatchSpec, FlagList) -> int() + Set trace patterns for tracing of function calls + + MFA, MatchSpec, FlagList -- see below + + +

This BIF is used to enable or disable call tracing for + exported functions. It must be combined with + erlang:trace/3 + to set the call trace flag for one or more processes.

+

Conceptually, call tracing works like this: Inside + the Erlang virtual machine there is a set of processes to be + traced and a set of functions to be traced. Tracing will be + enabled on the intersection of the set. That is, if a process + included in the traced process set calls a function included + in the traced function set, the trace action will be taken. + Otherwise, nothing will happen.

+

Use + erlang:trace/3 to + add or remove one or more processes to the set of traced + processes. Use erlang:trace_pattern/2 to add or remove + exported functions to the set of traced functions.

+

The erlang:trace_pattern/3 BIF can also add match + specifications to an exported function. A match specification + comprises a pattern that the arguments to the function must + match, a guard expression which must evaluate to true + and an action to be performed. The default action is to send a + trace message. If the pattern does not match or the guard + fails, the action will not be executed.

+

The MFA argument should be a tuple like + {Module, Function, Arity} or the atom on_load + (described below). It can be the module, function, and arity + for an exported function (or a BIF in any module). + The '_' atom can be used to mean any of that kind. + Wildcards can be used in any of the following ways:

+ + {Module,Function,'_'} + +

All exported functions of any arity named Function + in module Module.

+ + {Module,'_','_'} + +

All exported functions in module Module.

+ + {'_','_','_'} + +

All exported functions in all loaded modules.

+ + +

Other combinations, such as {Module,'_',Arity}, are + not allowed. Local functions will match wildcards only if + the local option is in the FlagList.

+

If the MFA argument is the atom on_load, + the match specification and flag list will be used on all + modules that are newly loaded.

+

The MatchSpec argument can take any of the following + forms:

+ + false + +

Disable tracing for the matching function(s). Any match + specification will be removed.

+ + true + +

Enable tracing for the matching function(s).

+ + MatchSpecList + +

A list of match specifications. An empty list is + equivalent to true. See the ERTS User's Guide + for a description of match specifications.

+ + restart + +

For the FlagList option call_count: + restart the existing counters. The behaviour is undefined + for other FlagList options.

+ + pause + +

For the FlagList option call_count: pause + the existing counters. The behaviour is undefined for + other FlagList options.

+ + +

The FlagList parameter is a list of options. + The following options are allowed:

+ + global + +

Turn on or off call tracing for global function calls + (that is, calls specifying the module explicitly). Only + exported functions will match and only global calls will + generate trace messages. This is the default.

+ + local + +

Turn on or off call tracing for all types of function + calls. Trace messages will be sent whenever any of + the specified functions are called, regardless of how they + are called. If the return_to flag is set for + the process, a return_to message will also be sent + when this function returns to its caller.

+ + meta | {meta, Pid} + +

Turn on or off meta tracing for all types of function + calls. Trace messages will be sent to the tracer process + or port Pid whenever any of the specified + functions are called, regardless of how they are called. + If no Pid is specified, self() is used as a + default tracer process.

+

Meta tracing traces all processes and does not care + about the process trace flags set by trace/3, + the trace flags are instead fixed to + [call, timestamp].

+

The match spec function {return_trace} works with + meta trace and send its trace message to the same tracer + process.

+ + call_count + +

Starts (MatchSpec == true) or stops + (MatchSpec == false) call count tracing for all + types of function calls. For every function a counter is + incremented when the function is called, in any process. + No process trace flags need to be activated.

+

If call count tracing is started while already running, + the count is restarted from zero. Running counters can be + paused with MatchSpec == pause. Paused and running + counters can be restarted from zero with + MatchSpec == restart.

+

The counter value can be read with + erlang:trace_info/2.

+ + +

The global and local options are mutually + exclusive and global is the default (if no options are + specified). The call_count and meta options + perform a kind of local tracing, and can also not be combined + with global. 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 + tracing for the matching set of local functions will be + disabled, and vice versa.

+

When disabling trace, the option must match the type of trace + that is set on the function, so that local tracing must be + disabled with the local option and global tracing with + the global option (or no option at all), and so forth.

+

There is no way to directly change part of a match + specification list. If a function has a match specification, + you can replace it with a completely new one. If you need to + change an existing match specification, use the + erlang:trace_info/2 + BIF to retrieve the existing match specification.

+

Returns the number of exported functions that matched + the MFA argument. This will be zero if none matched at + all.

+ + + + trunc(Number) -> int() + Return an integer by the truncating a number + + Number = number() + + +

Returns an integer by the truncating Number.

+ 
+> trunc(5.5).
+5
+

Allowed in guard tests.

+ + + + tuple_size(Tuple) -> int() + Return the size of a tuple + + Tuple = tuple() + + +

Returns an integer which is the number of elements in Tuple.

+ 
+> tuple_size({morni, mulle, bwange}).
+3
+

Allowed in guard tests.

+ + + + tuple_to_list(Tuple) -> [term()] + Convert a tuple to a list + + Tuple = tuple() + + +

Returns a list which corresponds to Tuple. + Tuple may contain any Erlang terms.

+ 
+> tuple_to_list({share, {'Ericsson_B', 163}}).
+[share,{'Ericsson_B',163}]
+ + + + erlang:universaltime() -> {Date, Time} + Current date and time according to Universal Time Coordinated (UTC) + + Date = {Year, Month, Day} + Time = {Hour, Minute, Second} +  Year = Month = Day = Hour = Minute = Second = int() + + +

Returns the current date and time according to Universal + Time Coordinated (UTC), also called GMT, in the form + {{Year, Month, Day}, {Hour, Minute, Second}} if + supported by the underlying operating system. If not, + erlang:universaltime() is equivalent to + erlang:localtime().

+ 
+> erlang:universaltime().
+{{1996,11,6},{14,18,43}}
+ + + + erlang:universaltime_to_localtime({Date1, Time1}) -> {Date2, Time2} + Convert from Universal Time Coordinated (UTC) to local date and time + + Date1 = Date2 = {Year, Month, Day} + Time1 = Time2 = {Hour, Minute, Second} +  Year = Month = Day = Hour = Minute = Second = int() + + +

Converts Universal Time Coordinated (UTC) date and time to + local date and time, if this is supported by the underlying + OS. Otherwise, no conversion is done, and + {Date1, Time1} is returned.

+ 
+> erlang:universaltime_to_localtime({{1996,11,6},{14,18,43}}).
+{{1996,11,7},{15,18,43}}
+

Failure: badarg if Date1 or Time1 do + not denote a valid date or time.

+ + + + unlink(Id) -> true + Remove a link, if there is one, to another process or port + + Id = pid() | port() + + +

Removes the link, if there is one, between the calling + process and the process or port referred to by Id.

+

Returns true and does not fail, even if there is no + link to Id, or if Id does not exist.

+

Once unlink(Id) has returned it is guaranteed that + the link between the caller and the entity referred to by + Id has no effect on the caller in the future (unless + the link is setup again). If caller is trapping exits, an + {'EXIT', Id, _} message due to the link might have + been placed in the callers message queue prior to the call, + though. Note, the {'EXIT', Id, _} message can be the + result of the link, but can also be the result of Id + calling exit/2. Therefore, it may be + appropriate to cleanup the message queue when trapping exits + after the call to unlink(Id), as follow:

+ + + unlink(Id), + receive +\011{'EXIT', Id, _} -> +\011 true + after 0 -> +\011 true + end + +

Prior to OTP release R11B (erts version 5.5) unlink/1 + behaved completely asynchronous, i.e., the link was active + until the "unlink signal" reached the linked entity. This + had one undesirable effect, though. You could never know when + you were guaranteed not to be effected by the link.

+

Current behavior can be viewed as two combined operations: + asynchronously send an "unlink signal" to the linked entity + and ignore any future results of the link.

+ + + + + unregister(RegName) -> true + Remove the registered name for a process (or port) + + RegName = atom() + + +

Removes the registered name RegName, associated with a + pid or a port identifier.

+ 
+> unregister(db).
+true
+

Users are advised not to unregister system processes.

+

Failure: badarg if RegName is not a registered + name.

+ + + + whereis(RegName) -> pid() | port() | undefined + Get the pid (or port) with a given registered name + +

Returns the pid or port identifier with the registered name + RegName. Returns undefined if the name is not + registered.

+ 
+> whereis(db).
+<0.43.0>
+ + + + erlang:yield() -> true + Let other processes get a chance to execute + +

Voluntarily let other processes (if any) get a chance to + execute. Using erlang:yield() is similar to + receive after 1 -> ok end, except that yield() + is faster.

+

There is seldom or never any need to use this BIF, + especially in the SMP-emulator as other processes will have a + chance to run in another scheduler thread anyway. + Using this BIF without a thorough grasp of how the scheduler + works may cause performance degradation.

 + + + + + diff --git a/erts/doc/src/erlc.xml b/erts/doc/src/erlc.xml new file mode 100644 index 0000000000..3859ac8365 --- /dev/null +++ b/erts/doc/src/erlc.xml @@ -0,0 +1,256 @@ + + + + +
+ + 19972009 + Ericsson AB. 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. + + + + erlc + Björn Gustavsson + Bjarne Däcker + 1 + Bjarne Däcker + + 97-03-24 + A + erlc.xml +
+ erlc + Compiler + +

The program provides a common way to run + all compilers in the Erlang system. + Depending on the extension of each input file, + will invoke the appropriate compiler. + Regardless of which compiler is used, the same flags are used to provide parameters such as include paths and output directory.

+

The current working directory, ".", will not be included + in the code path when running the compiler (to avoid loading + Beam files from the current working directory that could potentially + be in conflict with the compiler or Erlang/OTP system used by the + compiler).

+ + + + erlc flags file1.ext file2.ext... + Compile files + +

compiles one or more files. + The files must include the extension, for example + for Erlang source code, or for Yecc source code. + uses the extension to invoke the correct compiler.

+ + + + +
+ Generally Useful Flags +

The following flags are supported: +

+ + -I directory + +

Instructs the compiler to search for include files in + the specified directory. When encountering an + or directive, the + compiler searches for header files in the following + directories:

+ + +

, the current working directory of the + file server;

+ + +

the base name of the compiled file;

+ + +

the directories specified using the option. + The directory specified last is searched first.

+ + + + -o directory + +

The directory where the compiler should place the output files. + If not specified, output files will be placed in the current working + directory.

+ + -Dname + +

Defines a macro.

+ + -Dname=value + +

Defines a macro with the given value. + The value can be any Erlang term. + Depending on the platform, the value may need to be + quoted if the shell itself interprets certain characters. + On Unix, terms which contain tuples and list + must be quoted. Terms which contain spaces + must be quoted on all platforms.

+ + -Wnumber + +

Sets warning level to number. Default is . + Use to turn off warnings.

+ + -W + +

Same as . Default.

+ + -v + +

Enables verbose output.

+ + -b output-type + +

Specifies the type of output file. + Generally, output-type is the same as the file extension + of the output file but without the period. + This option will be ignored by compilers that have a + a single output format.

+ + -hybrid + +

Compile using the hybrid-heap emulator. This is mainly useful + for compiling native code, which needs to be compiled with the same + run-time system that it should be run on.

+ + -smp + +

Compile using the SMP emulator. This is mainly useful + for compiling native code, which needs to be compiled with the same + run-time system that it should be run on.

+ + -- + +

Signals that no more options will follow. + The rest of the arguments will be treated as file names, + even if they start with hyphens.

+ + +term + +

A flag starting with a plus ('+') rather than a hyphen + will be converted to an Erlang term and passed unchanged to + the compiler. + For instance, the option for the Erlang + compiler can be specified as follows:

+ 
+erlc +export_all file.erl
+

Depending on the platform, the value may need to be + quoted if the shell itself interprets certain characters. + On Unix, terms which contain tuples and list + must be quoted. Terms which contain spaces + must be quoted on all platforms.

+ + +
+ +
+ Special Flags +

The flags in this section are useful in special situations + such as re-building the OTP system.

+ + -pa directory + +

Appends directory to the front of the code path in + the invoked Erlang emulator. + This can be used to invoke another + compiler than the default one.

+ + -pz directory + +

Appends directory to the code path in + the invoked Erlang emulator.

+ + +
+ +
+ Supported Compilers + + .erl + +

Erlang source code. It generates a file.

+

The options -P, -E, and -S are equivalent to +'P', + +'E', and +'S', except that it is not necessary to include the single quotes to protect them + from the shell.

+

Supported options: -I, -o, -D, -v, -W, -b.

+ + .yrl + +

Yecc source code. It generates an file.

+

Use the -I option with the name of a file to use that file + as a customized prologue file (the option).

+

Supported options: -o, -v, -I, -W (see above).

+ + .mib + +

MIB for SNMP. It generates a file.

+

Supported options: -I, -o, -W.

+ + .bin + +

A compiled MIB for SNMP. It generates a file.

+

Supported options: -o, -v.

+ + .rel + +

Script file. It generates a boot file.

+

Use the -I to name directories to be searched for application + files (equivalent to the in the option list for + ).

+

Supported options: -o.

+ + .asn1 + +

ASN1 file.

+

Creates an , , and file from + an file. Also compiles the using the Erlang + compiler unless the options is given.

+

Supported options: -I, -o, -b, -W.

+ + .idl + +

IC file.

+

Runs the IDL compiler.

+

Supported options: -I, -o.

+ + +
+ +
+ Environment Variables + + ERLC_EMULATOR + The command for starting the emulator. + Default is erl in the same directory as the erlc program + itself, or if it doesn't exist, erl in any of the directories + given in the PATH environment variable. + +
+ +
+ SEE ALSO +

erl(1), + compile(3), + yecc(3), + snmp(3)

+
+ + diff --git a/erts/doc/src/erlsrv.xml b/erts/doc/src/erlsrv.xml new file mode 100644 index 0000000000..93db56fc7c --- /dev/null +++ b/erts/doc/src/erlsrv.xml @@ -0,0 +1,405 @@ + + + + +
+ + 19982009 + Ericsson AB. 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. + + + + erlsrv + Patrik Nyblom + + + + + 98-04-29 + + erlsrv.xml +
+ erlsrv + Run the Erlang emulator as a service on Windows NT® + +

This utility is specific to Windows NT/2000/XP® (and subsequent versions of Windows) It allows Erlang + emulators to run as services on the Windows system, allowing embedded + systems to start without any user needing to log in. The + emulator started in this way can be manipulated through the + Windows® services applet in a manner similar to other + services.

+

Note that erlsrv is not a general service utility for Windows, but designed for embedded Erlang systems.

+

As well as being the actual service, erlsrv also provides a + command line interface for registering, changing, starting and + stopping services.

+

To manipulate services, the logged in user should have + Administrator privileges on the machine. The Erlang machine + itself is (default) run as the local administrator. This can be + changed with the Services applet in Windows ®.

+

The processes created by the service can, as opposed to normal + services, be "killed" with the task manager. Killing a emulator + that is started by a service will trigger the "OnFail" action + specified for that service, which may be a reboot.

+

The following parameters may be specified for each Erlang + service:

+ + +

: This tells how to stop + the Erlang emulator. Default is to kill it (Win32 + TerminateProcess), but this action can specify any Erlang + shell command that will be executed in the emulator to make + it stop. The emulator is expected to stop within 30 seconds + after the command is issued in the shell. If the emulator is + not stopped, it will report a running state to the service + manager.

+ + +

: This can be either of , + , or (the + default). In case of , the NT system is + rebooted whenever the emulator stops (a more simple form of + watchdog), this could be useful for less critical systems, + otherwise use the heart functionality to accomplish + this. The restart value makes the Erlang emulator be + restarted (with whatever parameters are registered for the + service at the occasion) when it stops. If the emulator + stops again within 10 seconds, it is not restarted to avoid + an infinite loop which could completely hang the NT + system. is similar to restart, but + does not try to detect cyclic restarts, it is expected that + some other mechanism is present to avoid the problem. The + default (ignore) just reports the service as stopped to the + service manager whenever it fails, it has to be manually + restarted.

+

On a system where release handling is + used, this should always be set to . Use + to restart the service on failure instead.

+ + +

: The location of the Erlang + emulator. The default is the located in the + same directory as erlsrv.exe. Do not specify + as this emulator, it will not work.

+

If the system + uses release handling, this should be set to a program + similar to .

+ + +

: Specifies an additional environment + for the emulator. The environment variables specified + here are added to the system wide environment block that is + normally present when a service starts up. Variables present + in both the system wide environment and in the service + environment specification will be set to the value specified + in the service.

+ + +

: The working directory for the Erlang + emulator, has to be on a local drive (there are no network + drives mounted when a service starts). Default working + directory for services is . + Debug log files will be placed in this directory.

+ + +

: The process priority of the emulator, + this can be one of , , + or (the default). Real-time priority is not + recommended, the machine will possibly be inaccessible to + interactive users. High priority could be used if two Erlang + nodes should reside on one dedicated system and one should + have precedence over the other. Low process priority may be + used if interactive performance should not be affected by + the emulator process.

+ + +

: Specifies the short or long + node-name of the Erlang emulator. The Erlang services are + always distributed, default is to use the service name as + (short) node-name.

+ + +

: Can be one of (default), + , or . + Specifies that output from the Erlang shell should be + sent to a "debug log". The log file is named + <servicename> or + <servicename><N>, where <N> is + an integer between 1 and 99. The log-file is placed in the + working directory of the service (as specified in WorkDir). The + option always reuses the same log file + (<servicename>) and the option + uses a separate log file for every invocation of the service + (<servicename><N>). The + option opens an interactive Windows® console window for + the Erlang shell of the service. The option + automatically + disables the and a service started with an + interactive console window will not survive logouts, + actions do not work with debug-consoles either. + If no is specified (), the + output of the Erlang shell is discarded.

+

The is not in any way + intended for production. It is only a convenient way to + debug Erlang services during development. The and + options might seem convenient to have in a + production system, but one has to take into account that the + logs will grow indefinitely during the systems lifetime and + there is no way, short of restarting the service, to + truncate those logs. In short, the is + intended for debugging only. Logs during production are + better produced with the standard Erlang logging + facilities.

+ + +

: Additional arguments passed to the + emulator startup program (or + ). Arguments that cannot be specified + here are (StopActions would not work), + and (they are specified in any + way. The most common use is for specifying cookies and flags + to be passed to init:boot() ().

+ + +

: Specifies the Windows® internal service name (not the display name, which is the one erlsrv uses to identify the service).

+

This internal name can not be changed, it is fixed even if the service is renamed. Erlsrv generates a unique internal name when a service is created, it is recommended to keep to the defaut if release-handling is to be used for the application.

+

The internal service name can be seen in the Windows® service manager if viewing Properties for an erlang service.

+ + +

: A textual comment describing the service. Not mandatory, but shows up as the service description in the Windows® service manager.

+ + +

+ The naming of the service in a system that + uses release handling has to follow the convention + NodeName_Release, where NodeName is + the first part of the Erlang nodename (up to, but not including + the "@") and Release is the current release of the + application.

+ + + + erlsrv {set | add} <service-name> [<service options>] + Add or modify an Erlang service + +

The set and add commands adds or modifies a Erlang service + respectively. The simplest form of an add command would be + completely without options in which case all default values + (described above) apply. The service name is mandatory.

+

Every option can be given without parameters, in which case + the default value is applied. Values to the options are + supplied only when the default should not be used + (i.e. sets the + default priority and removes all arguments).

+

The following service options are currently available:

+ + -st[opaction] [<erlang shell command>] + Defines the StopAction, the command given to the Erlang + shell when the service is stopped. Default is none. + -on[fail] [{reboot | restart | restart_always}] + Specifies the action to take when the Erlang emulator + stops unexpectedly. Default is to ignore. + -m[achine] [<erl-command>] + The complete path to the Erlang emulator, never use the + werl program for this. Default is the in the + same directory as . When release handling + is used, this should be set to a program similar to + . + -e[nv] [<variable>[=<value>]] ... + Edits the environment block for the service. Every + environment variable specified will add to the system + environment block. If a variable specified here has the same + name as a system wide environment variable, the specified + value overrides the system wide. Environment variables are + added to this list by specifying + <variable>=<value> and deleted from the list by + specifying <variable> alone. The environment block is + automatically sorted. Any number of options can + be specified in one command. Default is to use the system + environment block unmodified (except for two additions, see + below). + -w[orkdir] [<directory>] + The initial working directory of the Erlang + emulator. Default is the system directory. + -p[riority] [{low|high|realtime}] + The priority of the Erlang emulator. The default is the + Windows® default priority. + {-sn[ame] | -n[ame]} [<node-name>] + The node-name of the Erlang machine, distribution is + mandatory. Default is ]]>. + + -d[ebugtype] [{new|reuse|console}] + Specifies where shell output should be sent, + default is that shell output is discarded. + To be used only for debugging. + -ar[gs] [<limited erl arguments>] + Additional arguments to the Erlang emulator, avoid + , and + /. Default is no additional + arguments. Remember that the services cookie file is not + necessarily the same as the interactive users. The service + runs as the local administrator. All arguments should be given + together in one string, use double quotes (") to give an + argument string containing spaces and use quoted quotes (\\") + to give an quote within the argument string if + necessary. + -i[nternalservicename] [<internal name>] + Only allowed for add. Specifies a + Windows® internal service name for the service, which by + default is set to something unique (prefixed with the + original service name) by erlsrv when adding a new + service. Specifying this is a purely cosmethic action and is + not recommended if release handling is to be + performed. The internal service name cannot be changed once + the service is created. The internal name is not to + be confused with the ordinary service name, which is the name + used to identify a service to erlsrv. + -c[omment] [<short description>] + Specifies a textual comment describing the + service. This comment will show upp as the service description + in the Windows® service manager. + + + + + erlsrv {start | stop | disable | enable} <service-name> + Manipulate the current service status. + +

These commands are only added for convenience, the normal + way to manipulate the state of a service is through the + control panels services applet. The and + commands communicates + with the service manager for stopping and starting a + service. The commands wait until the service is actually + stopped or started. When disabling a service, it is not + stopped, the disabled state will not take effect until the + 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.

+ + + + erlsrv remove <service-name> + Remove the service. + +

This command removes the service completely with all its registered + options. It will be stopped before it is removed.

+ + + + erlsrv list [<service-name>] + List all Erlang services or all options for one service. + +

If no service name is supplied, a brief listing of all Erlang services + is presented. If a service-name is supplied, all options for that + service are presented.

+ + + + erlsrv help + Display a brief help text + + + +
+ ENVIRONMENT +

+The environment of an Erlang machine started + as a service will contain two special variables, + , which is the name of the service that + started the machine and which is the + full path to the that can be used to manipulate + the service. This will come in handy when defining a heart command for + your service. A command file for restarting a service will + simply look like this:

+ +

This command file is then set as heart command.

+

The environment variables can also be used to detect that we + are running as a service and make port programs react correctly + to the control events generated on logout (see below).

+
+ +
+ PORT PROGRAMS +

When a program runs in + the service context, it has to handle the control events that is + sent to every program in the system when the interactive user + logs off. This is done in different ways for programs running in + the console subsystem and programs running as window + applications. An application which runs in the console subsystem + (normal for port programs) uses the win32 function + to a control handler that returns + TRUE in answer to the . Other + applications just forward and + to the default window procedure. Here + is a brief example in C of how to set the console control + handler:

+ +/* +** A Console control handler that ignores the log off events, +** and lets the default handler take care of other events. +*/ +BOOL WINAPI service_aware_handler(DWORD ctrl){ + if(ctrl == CTRL_LOGOFF_EVENT) +\011return TRUE; + return FALSE; +} + +void initialize_handler(void){ + char buffer[2]; + /* + * We assume we are running as a service if this + * environment variable is defined + */ + if(GetEnvironmentVariable("ERLSRV_SERVICE_NAME",buffer, + (DWORD) 2)){ +\011/* +\011** Actually set the control handler +\011*/ +\011SetConsoleCtrlHandler(&service_aware_handler, TRUE); + } +} ]]> +
+ +
+ NOTES +

Even though the options are described in a Unix-like format, the case of + the options or commands is not relevant, and the "/" character for options + can be used as well as the "-" character.

+

Note that the program resides in the emulators + -directory, not in the -directory directly under + the Erlang root. The reasons for this are the subtle problem of + upgrading the emulator on a running system, where a new version of + the runtime system should not need to overwrite existing (and probably + used) executables.

+

To easily manipulate the Erlang services, put + the \\erts-\\bin]]> directory in + the path instead of \\bin]]>. The erlsrv program + can be found from inside Erlang by using the + Erlang function.

+

For release handling to work, use as the Erlang + machine. It is also worth mentioning again that the name of the + service is significant (see above).

+
+ +
+ SEE ALSO +

start_erl(1), release_handler(3)

+
+ + diff --git a/erts/doc/src/erts_alloc.xml b/erts/doc/src/erts_alloc.xml new file mode 100644 index 0000000000..d51e5b3ea4 --- /dev/null +++ b/erts/doc/src/erts_alloc.xml @@ -0,0 +1,554 @@ + + + + +
+ + 20022009 + Ericsson AB. 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. + + + + erts_alloc + Rickard Green + 1 + 03-06-11 + 1 + erts_alloc.xml +
+ erts_alloc + An Erlang Run-Time System internal memory allocator library. + +

erts_alloc is an Erlang Run-Time System internal memory + allocator library. erts_alloc provides the Erlang + Run-Time System with a number of memory allocators.

+ + +
+ Allocators + +

Currently the following allocators are present:

+ + temp_alloc + Allocator used for temporary allocations. + eheap_alloc + Allocator used for Erlang heap data, such as Erlang process heaps. + binary_alloc + Allocator used for Erlang binary data. + ets_alloc + Allocator used for ETS data. + driver_alloc + Allocator used for driver data. + sl_alloc + Allocator used for memory blocks that are expected to be + short-lived. + ll_alloc + Allocator used for memory blocks that are expected to be + long-lived, for example Erlang code. + fix_alloc + A very fast allocator used for some fix-sized + data. fix_alloc manages a set of memory pools from + which memory blocks are handed out. fix_alloc + allocates memory pools from ll_alloc. Memory pools + that have been allocated are never deallocated. + std_alloc + Allocator used for most memory blocks not allocated via any of + the other allocators described above. + sys_alloc + This is normally the default malloc implementation + used on the specific OS. + mseg_alloc + A memory segment allocator. mseg_alloc is used by other + allocators for allocating memory segments and is currently only + available on systems that have the mmap system + call. Memory segments that are deallocated are kept for a + while in a segment cache before they are destroyed. When + 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. + +

sys_alloc and fix_alloc are always enabled and + cannot be disabled. mseg_alloc is always enabled if it is + available and an allocator that uses it is enabled. All other + allocators can be enabled or disabled. + By default all allocators are enabled. + When an allocator is disabled, sys_alloc + is used instead of the disabled allocator.

+

The main idea with the erts_alloc library is to separate + memory blocks that are used differently into different memory + areas, and by this achieving less memory fragmentation. By + putting less effort in finding a good fit for memory blocks that + are frequently allocated than for those less frequently + allocated, a performance gain can be achieved.

+
+ +
+ + The alloc_util framework +

Internally a framework called alloc_util is used for + implementing allocators. sys_alloc, fix_alloc, and + mseg_alloc do not use this framework; hence, the + following does not apply to them.

+

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 mseg_alloc) or in + the heap segment (allocated via sys_alloc). 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 + (sbct) parameter are placed + in singleblock carriers. Blocks smaller than the value of the + sbct parameter are placed in multiblock + carriers. 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 mmbcs parameter.

+

+ + Sizes of multiblock carriers allocated via mseg_alloc are + decided based on the values of the largest multiblock carrier + size (lmbcs), the smallest + multiblock carrier size (smbcs), + and the multiblock carrier growth stages + (mbcgs) parameters. If + nc is the current number of multiblock carriers (the main + multiblock carrier excluded) managed by an allocator, the size + of the next mseg_alloc multiblock carrier allocated by + this allocator will roughly be + when + , + and lmbcs when mbcgs]]>. If the value of the + sbct parameter should be larger than the value of the + lmbcs parameter, the allocator may have to create + multiblock carriers that are larger than the value of the + lmbcs parameter, though. Singleblock carriers allocated + via mseg_alloc are sized to whole pages.

+

Sizes of carriers allocated via sys_alloc are + decided based on the value of the sys_alloc carrier size + (ycs) parameter. The size of + a carrier is the least number of multiples of the value of the + ycs parameter that satisfies the request.

+

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.

+

+ + The memory allocation strategy used for multiblock carriers by an + allocator is configurable via the as + parameter. Currently the following strategies are available:

+ + Best fit + +

Strategy: Find the smallest block that satisfies the + requested block size.

+

Implementation: A balanced binary search tree is + used. The time complexity is proportional to log N, where + N is the number of sizes of free blocks.

+ + Address order best fit + +

Strategy: Find the smallest block that satisfies the + requested block size. If multiple blocks are found, choose + the one with the lowest address.

+

Implementation: A balanced binary search tree is + used. The time complexity is proportional to log N, where + N is the number of free blocks.

+ + Good fit + +

Strategy: Try to find the best fit, but settle for the best fit + found during a limited search.

+

Implementation: The implementation uses segregated free + lists with a maximum block search depth (in each list) in + order to find a good fit fast. When the maximum block + search depth is small (by default 3) this implementation + has a time complexity that is constant. The maximum block + search depth is configurable via the + mbsd parameter.

+ + A fit + +

Strategy: Do not search for a fit, inspect only one free + block to see if it satisfies the request. This strategy is + only intended to be used for temporary allocations.

+

Implementation: Inspect the first block in a free-list. + If it satisfies the request, it is used; otherwise, a new + carrier is created. The implementation has a time + complexity that is constant.

+

As of erts version 5.6.1 the emulator will refuse to + use this strategy on other allocators than temp_alloc. + This since it will only cause problems for other allocators.

+ + +
+ +
+ + System Flags Effecting erts_alloc + +

Only use these flags if you are absolutely sure what you are + doing. Unsuitable settings may cause serious performance + degradation and even a system crash at any time during + operation.

+ +

Memory allocator system flags have the following syntax: +

]]> + where ]]> is a letter identifying a subsystem, + ]]> is a parameter, and ]]> is the + value to use. The flags can be passed to the Erlang emulator + (erl) as command line + arguments.

+

System flags effecting specific allocators have an upper-case + letter as ]]>. The following letters are used for + the currently present allocators:

+ + B: binary_alloc + D: std_alloc + E: ets_alloc + F: fix_alloc + H: eheap_alloc + L: ll_alloc + M: mseg_alloc + R: driver_alloc + S: sl_alloc + T: temp_alloc + Y: sys_alloc + +

The following flags are available for configuration of + mseg_alloc:

+ + ]]> + + + Absolute max cache bad fit (in kilobytes). A segment in the + memory segment cache is not reused if its size exceeds the + requested size with more than the value of this + parameter. Default value is 4096. + ]]> + + + Relative max cache bad fit (in percent). A segment in the + memory segment cache is not reused if its size exceeds the + requested size with more than relative max cache bad fit + percent of the requested size. Default value is 20. + ]]> + + + Max cached segments. The maximum number of memory segments + stored in the memory segment cache. Valid range is + 0-30. Default value is 5. + ]]> + + + Cache check interval (in milliseconds). The memory segment + cache is checked for segments to destroy at an interval + determined by this parameter. Default value is 1000. + +

The following flags are available for configuration of + fix_alloc:

+ + +MFe true + + + Enable fix_alloc. Note: fix_alloc cannot be disabled. + +

The following flags are available for configuration of + sys_alloc:

+ + +MYe true + + + Enable sys_alloc. Note: sys_alloc cannot be disabled. + +MYm libc + +malloc library to use. Currently only + libc is available. libc enables the standard + libc malloc implementation. By default libc is used. + ]]> + + + Trim threshold size (in kilobytes). This is the maximum amount + of free memory at the top of the heap (allocated by + sbrk) that will be kept by malloc (not + released to the operating system). When the amount of free + memory at the top of the heap exceeds the trim threshold, + malloc will release it (by calling + sbrk). Trim threshold is given in kilobytes. Default + trim threshold is 128. Note: This flag will + only have any effect when the emulator has been linked with + the GNU C library, and uses its malloc implementation. + ]]> + + + Top pad size (in kilobytes). This is the amount of extra + memory that will be allocated by malloc when + sbrk is called to get more memory from the operating + system. Default top pad size is 0. Note: This flag + will only have any effect when the emulator has been linked + with the GNU C library, and uses its malloc + implementation. + +

The following flags are available for configuration of allocators + based on alloc_util. If u is used as subsystem + identifier (i.e., = u]]>) all allocators based on + alloc_util will be effected. If B, D, E, + H, L, R, S, or T is used as + subsystem identifier, only the specific allocator identified will be + effected:

+ + as bf|aobf|gf|af]]> + + + Allocation strategy. Valid strategies are bf (best fit), + aobf (address order best fit), gf (good fit), + and af (a fit). See + the description of allocation strategies in "the alloc_util framework" section. + asbcst ]]> + + + Absolute singleblock carrier shrink threshold (in + kilobytes). When a block located in an + mseg_alloc singleblock carrier is shrunk, the carrier + will be left unchanged if the amount of unused memory is less + than this threshold; otherwise, the carrier will be shrunk. + See also rsbcst. + e true|false]]> + + + Enable allocator ]]>. + lmbcs ]]> + + + Largest (mseg_alloc) multiblock carrier size (in + kilobytes). See the description + on how sizes for mseg_alloc multiblock carriers are decided + in "the alloc_util framework" section. + mbcgs ]]> + + + (mseg_alloc) multiblock carrier growth stages. See + the description on how sizes for + mseg_alloc multiblock carriers are decided + in "the alloc_util framework" section. + mbsd ]]> + + + Max block search depth. This flag has effect only if the + good fit strategy has been selected for allocator + ]]>. When the good fit strategy is used, free + blocks are placed in segregated free-lists. Each free list + contains blocks of sizes in a specific range. The max block + search depth sets a limit on the maximum number of blocks to + inspect in a free list during a search for suitable block + satisfying the request. + mmbcs ]]> + + + Main multiblock carrier size. Sets the size of the main + multiblock carrier for allocator ]]>. The main + multiblock carrier is allocated via and is + never deallocated. + mmmbc ]]> + + + Max mseg_alloc multiblock carriers. Maximum number of + multiblock carriers allocated via mseg_alloc by + allocator ]]>. When this limit has been reached, + new multiblock carriers will be allocated via + sys_alloc. + mmsbc ]]> + + + Max mseg_alloc singleblock carriers. Maximum number of + singleblock carriers allocated via mseg_alloc by + allocator ]]>. When this limit has been reached, + new singleblock carriers will be allocated via + sys_alloc. + ramv ]]> + + + Realloc always moves. When enabled, reallocate operations will + more or less be translated into an allocate, copy, free sequence. + This often reduce memory fragmentation, but costs performance. + + rmbcmt ]]> + + + Relative multiblock carrier move threshold (in percent). When + a block located in a multiblock carrier is shrunk, + the block will be moved if the ratio of the size of the returned + memory compared to the previous size is more than this threshold; + otherwise, the block will be shrunk at current location. + rsbcmt ]]> + + + Relative singleblock carrier move threshold (in percent). When + a block located in a singleblock carrier is shrunk to + a size smaller than the value of the + sbct parameter, + the block will be left unchanged in the singleblock carrier if + the ratio of unused memory is less than this threshold; + otherwise, it will be moved into a multiblock carrier. + rsbcst ]]> + + + Relative singleblock carrier shrink threshold (in + percent). When a block located in an mseg_alloc + singleblock carrier is shrunk, the carrier will be left + unchanged if the ratio of unused memory is less than this + threshold; otherwise, the carrier will be shrunk. + See also asbcst. + sbct ]]> + + + Singleblock carrier threshold. Blocks larger than this + threshold will be placed in singleblock carriers. Blocks + smaller than this threshold will be placed in multiblock + carriers. + smbcs ]]> + + + Smallest (mseg_alloc) multiblock carrier size (in + kilobytes). See the description + on how sizes for mseg_alloc multiblock carriers are decided + in "the alloc_util framework" section. + t true|false|]]> + + + 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 (N equals the number of scheduler threads): + + temp_alloc + N + 1 instances. + ll_alloc + 1 instance. + Other allocators + N instances when N is less than or equal to + 16. 16 instances when N is greater than + 16. + + temp_alloc will always use N + 1 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 N. + + +

Currently the following flags are available for configuration of + alloc_util, i.e. all allocators based on alloc_util + will be effected:

+ + ]]> + +sys_alloc carrier size. Carriers allocated via + sys_alloc will be allocated in sizes which are + multiples of the sys_alloc carrier size. This is not + true for main multiblock carriers and carriers allocated + during a memory shortage, though. + ]]> + + + Max mseg_alloc carriers. Maximum number of carriers + placed in separate memory segments. When this limit has been + reached, new carriers will be placed in memory retrieved from + sys_alloc. + +

Instrumentation flags:

+ + +Mim true|false + + + A map over current allocations is kept by the emulator. The + allocation map can be retrieved via the instrument + module. +Mim true implies +Mis true. + +Mim true is the same as + -instr. + +Mis true|false + + + Status over allocated memory is kept by the emulator. The + allocation status can be retrieved via the instrument + module. + +Mit X + + + Reserved for future use. Do not use this flag. + + +

When instrumentation of the emulator is enabled, the emulator + uses more memory and runs slower.

+ +

Other flags:

+ + +Mea min|max|r9c|r10b|r11b|config + + + min + + Disables all allocators that can be disabled. + + + max + + Enables all allocators (currently default). + + + r9c|r10b|r11b + + Configures all allocators as they were configured in respective + OTP release. These will eventually be removed. + + + config + + Disables features that cannot be enabled while creating an + allocator configuration with + erts_alloc_config(3). + Note, this option should only be used while running + erts_alloc_config, not when using the created + configuration. + + + + +

Only some default values have been presented + here. + erlang:system_info(allocator), + and + erlang:system_info({allocator, Alloc}) + can be used in order to obtain currently used settings and current + status of the allocators.

+ +

Most of these flags are highly implementation dependent, and they + may be changed or removed without prior notice.

+

erts_alloc is not obliged to strictly use the settings that + have been passed to it (it may even ignore them).

+ +

erts_alloc_config(3) + is a tool that can be used to aid creation of an + erts_alloc configuration that is suitable for a limited + number of runtime scenarios.

+
+ +
+ SEE ALSO +

erts_alloc_config(3), + erl(1), + instrument(3), + erlang(3)

+
+ + diff --git a/erts/doc/src/escript.xml b/erts/doc/src/escript.xml new file mode 100644 index 0000000000..8df179b3e2 --- /dev/null +++ b/erts/doc/src/escript.xml @@ -0,0 +1,232 @@ + + + + +
+ + 20072009 + Ericsson AB. 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. + + + + escript + + + + + escript.xml +
+ escript + Erlang scripting support + +

provides support for running short Erlang programs + without having to compile them first and an easy way to retrieve the + command line arguments.

+ + + + script-name script-arg1 script-arg2... + escript escript-flags script-name script-arg1 script-arg2... + Run a script written in Erlang + +

runs a script written in Erlang.

+

Here follows an example.

+ 
+$ cat factorial        
+#!/usr/bin/env escript
+%% -*- erlang -*-
+%%! -smp enable -sname factorial -mnesia debug verbose
+main([String]) ->
+    try
+\011N = list_to_integer(String),
+\011F = fac(N),
+\011io:format("factorial ~w = ~w\
+", [N,F])
+    catch
+\011_:_ ->
+\011    usage()
+    end;
+main(_) ->
+    usage().
+        
+usage() ->
+    io:format("usage: factorial integer\
+"),
+    halt(1).
+        
+fac(0) -> 1;
+fac(N) -> N * fac(N-1).
+$ factorial 5
+factorial 5 = 120
+$ factorial
+usage: factorial integer
+$ factorial five
+usage: factorial integer
+

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 + . However if you invoke the + like this

+ 
+$ escript factorial 5
+

the contents of the first line does not matter, but it + cannot contain Erlang code as it will be ignored.

+

The second line in the example, contains an optional + directive to the Emacs editor which causes it to + enter the major mode for editing Erlang source files. If the + directive is present it must be located on the second + line.

+

On the third line (or second line depending on the presence + of the Emacs directive), it is possible to give arguments to + the emulator, such as

+ 
+%%! -smp enable -sname factorial -mnesia debug verbose
+

Such an argument line must start with %%! and the + rest of the line will interpreted as arguments to the emulator.

+

If you know the location of the executable, the first + line can directly give the path to . For instance:

+ 
+#!/usr/local/bin/escript
+

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 to turn on the execution bit.) +

+ +

The rest of the Erlang script file may either contain + Erlang source code, an inlined beam file or an + inlined archive file.

+ +

An Erlang script file must always contain the function + main/1. When the script is run, the + function will be called with a list + of strings representing the arguments given to the script (not + changed or interpreted in any way).

+ +

If the 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.

+ +

To return your own non-zero exit code, call ; + for instance:

+ 
+halt(1).
+ +

Call from your to + script to retrieve the pathname of the script (the pathname + is usually, but not always, absolute).

+ +

If the file contains source code (as in the example above), + it will be processed by the preprocessor epp. This + means that you for example may use pre-defined macros (such as + ) as well as include directives like + the directive. For instance, use

+ 
+-include_lib("kernel/include/file.hrl").
+

to include the record definitions for the records used by the + function.

+ +

The script will be checked for syntactic and semantic + correctness before being run. If there are warnings (such as + unused variables), they will be printed and the script will + still be run. If there are errors, they will be printed and + the script will not be run and its exit status will be + 127.

+ +

Both the module declaration and the export declaration of + the function are optional.

+ +

By default, the script will be interpreted. You can force + it to be compiled by including the following line somewhere + in the script file:

+-mode(compile).
+ +

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.

+ +

As mentioned earlier, it is possible to have a script which + contains precompiled beam code. In a precompiled + script, the interpretation of the script header is exactly + the same as in a script containing source code. That means + that you can make a beam file executable by + prepending the file with the lines starting with #! + and %%! mentioned above. In a precompiled script, the + function + main/1 must be exported.

+ +

As yet another option it is possible to have an entire + Erlang archive in the script. In a archive script, the + interpretation of the script header is exactly the same as + in a script containing source code. That means that you can + make an archive file executable by prepending the file with + the lines starting with #! and %%! mentioned + above. In an archive script, the function main/1 must + be exported. By default the main/1 function in the + module with the same name as the basename of the + escript file will be invoked. This behavior can be + overridden by setting the flag -escript main Module + as one of the emulator flags. The Module must be the + name of a module which has an exported main/1 + function. See code(3) + for more information about archives and code loading.

+ +

In many cases it is very convenient to have a header in + the escript, especially on Unix platforms. But the header is + in fact optional. This means that you directly can "execute" + an Erlang module, beam file or archive file without adding + any header to them. But then you have to invoke the script + like this:

+ 
+$ escript factorial.erl 5
+factorial 5 = 120
+$ escript factorial.beam 5
+factorial 5 = 120
+$ escript factorial.zip 5
+factorial 5 = 120
+
+ + + + +
+ Options accepted by escript + + -c + Compile the escript regardless of the value of the mode attribute. + + + -d + Debug the escript. Starts the debugger, loads the module + containing the main/1 function into the debugger, sets a + breakpoint in main/1 and invokes main/1. If the + module is precompiled, it must be explicitly compiled with the + debug_info option. + + + -i + Interpret the escript regardless of the value of the mode attribute. + + + -s + Only perform a syntactic and semantic check of the script file. + 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. + +
+ + diff --git a/erts/doc/src/fascicules.xml b/erts/doc/src/fascicules.xml new file mode 100644 index 0000000000..cae197a516 --- /dev/null +++ b/erts/doc/src/fascicules.xml @@ -0,0 +1,18 @@ + + + + + + ERTS User's Guide + + + ERTS Reference Manual + + + Release Notes + + + Off-Print + + + diff --git a/erts/doc/src/inet_cfg.xml b/erts/doc/src/inet_cfg.xml new file mode 100644 index 0000000000..18cf65759a --- /dev/null +++ b/erts/doc/src/inet_cfg.xml @@ -0,0 +1,397 @@ + + + + +
+ + 20042009 + Ericsson AB. 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. + + + + Inet configuration + Peter Andersson + + 2004-03-02 + PA1 + inet_cfg.xml +
+ +
+ Introduction +

This chapter tells you how the Erlang runtime system is configured + for IP communication. It also explains how you may configure it + for your own particular needs by means of a configuration file. + The information here is mainly intended for users with special + configuration needs or problems. There should normally be no need + for specific settings for Erlang to function properly on a correctly + IP configured platform.

+

When Erlang starts up it will read the kernel variable + which, if defined, should specify the location and + name of a user configuration file. Example:

+

+

Note that the usage of a file, which was + supported in earlier Erlang versions, is now obsolete.

+

A second way to specify the configuration file is to set the + environment variable to the full name of the file. Example (bash):

+

+

Note that the kernel variable overrides this environment variable.

+

If no user configuration file is specified and Erlang is started + in non-distributed or short name distributed mode, Erlang will use + default configuration settings and a native lookup method that should + work correctly under most circumstances. Erlang + will not read any information from system inet configuration files + (like /etc/host.conf, /etc/nsswitch.conf, etc) in these modes, + except for /etc/resolv.conf and /etc/hosts that is read and monitored + for changes on Unix platforms for the internal DNS client + inet_res.

+

If Erlang is started in long name distributed mode, it needs to + get the domain name from somewhere and will read system inet + configuration files for this information. Any hosts and resolver + information found then is also recorded, but not + used as long as Erlang is configured for native lookups. (The + information becomes useful if the lookup method is changed to + or , see below).

+

Native lookup (system calls) is always the default resolver method. This + is true for all platforms except VxWorks and OSE Delta where + or is used (in that order of priority).

+

On Windows platforms, Erlang will search the system registry rather than + look for configuration files when started in long name distributed mode.

+
+ +
+ Configuration Data +

Erlang records the following data in a local database if found in system + inet configuration files (or system registry):

+ + Host names and addresses + Domain name + Nameservers + Search domains + Lookup method + +

This data may also be specified explicitly in the user + configuration file. The configuration file should contain lines + of configuration parameters (each terminated with a full + stop). Some parameters add data to the configuration (e.g. host + and nameserver), others overwrite any previous settings + (e.g. domain and lookup). The user configuration file is always + examined last in the configuration process, making it possible + for the user to override any default values or previously made + settings. Call to view the state of the + inet configuration database.

+

These are the valid configuration parameters:

+

+ + + +

+

+

+

+

Specify a system file that Erlang should read configuration + data from. tells the parser how the file should be + interpreted: (Unix resolv.conf), + (FreeBSD host.conf), (BSDOS host.conf), + (Linux host.conf), + (Unix nsswitch.conf) or (Unix hosts). should + specify the name of the file with full path.

+

+ + + +

+

+

+

Specify a system file that Erlang should read resolver + configuration from for the internal DNS client + inet_res, + and monitor for changes, even if it does not exist. + The path must be absolute.

+

This may override the configuration parameters + and + depending on the contents + of the specified file. They may also change any time in the future + reflecting the file contents.

+

If the file is specified as an empty string "", + no file is read nor monitored in the future. This emulates + the old behaviour of not configuring the DNS client when + the node is started in short name distributed mode.

+

If this parameter is not specified it defaults to + unless the environment variable + is set which defines + the directory for this file to some maybe other than + .

+

+ + + +

+

+

+

Specify a system file that Erlang should read resolver + configuration from for the internal hosts file resolver + and monitor for changes, even if it does not exist. + The path must be absolute.

+

These host entries are searched after all added with + {file, hosts, File} above or + {host, IP, Aliases} below when the lookup option + file is used.

+

If the file is specified as an empty string "", + no file is read nor monitored in the future. This emulates + the old behaviour of not configuring the DNS client when + the node is started in short name distributed mode.

+

If this parameter is not specified it defaults to + unless the environment variable + is set which defines + the directory for this file to some maybe other than + .

+

+ + + +

+

+

+

Specify a system registry that Erlang should read configuration + data from. Currently, is the only valid option.

+

+ + + +

+

+

+

+

Add host entry to the hosts table.

+

+ + + +

+

+

+

Set domain name.

+

+ + + +

+

+

+

+

Add address (and port, if other than default) of primary + nameserver to use for + inet_res.

+

+ + + +

+

+

+

+

Add address (and port, if other than default) of secondary + nameserver for + inet_res.

+

+ + + +

+

+

+

Add search domains for + inet_res.

+

+ + + +

+

+

+

Specify lookup methods and in which order to try them. + The valid methods are: (use system calls), + (use host data retrieved from + system configuration files and/or + the user configuration file) or + (use the Erlang DNS client + inet_res + for nameserver queries).

+

+ + + +

+

+

+

Set size of resolver cache. Default is 100 DNS records.

+

+ + + +

+

+

+

Set how often (in millisec) + the resolver cache for + inet_res. + is refreshed (i.e. expired DNS records are deleted). + Default is 1 h.

+

+ + + +

+

+

+

Set the time to wait until retry (in millisec) for DNS queries + made by + inet_res. + Default is 2 sec.

+

+ + + +

+

+

+

Set the number of DNS queries + inet_res + will try before giving up. + Default is 3.

+

+ + + +

+

+

+

Tells the DNS client + inet_res + to look up IPv6 addresses. Default is false.

+

+ + + +

+

+

+

Tells the DNS client + inet_res + to use TCP (Virtual Circuit) instead of UDP. Default is false.

+

+ + + +

+

+

+

Sets the EDNS version that + inet_res + will use. The only allowed is zero. Default is false + which means to not use EDNS.

+

+ + + +

+

+

+

Sets the allowed UDP payload size + inet_res + will advertise in EDNS queries. Also sets the limit + when the DNS query will be deemed too large for UDP + forcing a TCP query instead, which is not entirely + correct since the advertised UDP payload size of the + individual nameserver is what should be used, + but this simple strategy will do until a more intelligent + (probing, caching) algorithm need be implemented. + The default is 1280 which stems from the + standard Ethernet MTU size.

+

+ + + +

+

+

+

Tell Erlang to use other primitive UDP module than inet_udp.

+

+ + + +

+

+

+

Tell Erlang to use other primitive TCP module than inet_tcp.

+

+ + + +

+

Clear the hosts table.

+

+ + + +

+

Clear the list of recorded nameservers (primary and secondary).

+

+ + + +

+

Clear the list of search domains.

+

+ + +
+ +
+ User Configuration Example +

Here follows a user configuration example.

+

Assume a user does not want Erlang to use the native lookup method, + but wants Erlang to read all information necessary from start and use + that for resolving names and addresses. In case lookup fails, Erlang + should request the data from a nameserver (using the Erlang + DNS client, set to use EDNS allowing larger responses). + The resolver configuration will be updated when + its configuration file changes, furthermore, DNS records + should never be cached. The user configuration file + (in this example named , stored + in directory ) could then look like this + (Unix):

+ 
+      %% -- ERLANG INET CONFIGURATION FILE --
+      %% read the hosts file
+      {file, hosts, "/etc/hosts"}.
+      %% add a particular host
+      {host, {134,138,177,105}, ["finwe"]}.
+      %% do not monitor the hosts file
+      {hosts_file, ""}.
+      %% read and monitor nameserver config from here
+      {resolv_conf, "/usr/local/etc/resolv.conf"}.
+      %% enable EDNS
+      {edns,0}.
+      %% disable caching
+      {cache_size, 0}.
+      %% specify lookup method
+      {lookup, [file, dns]}.
+

And Erlang could, for example, be started like this:

+

+
+ + diff --git a/erts/doc/src/init.xml b/erts/doc/src/init.xml new file mode 100644 index 0000000000..33364c709a --- /dev/null +++ b/erts/doc/src/init.xml @@ -0,0 +1,384 @@ + + + + +
+ + 19962009 + Ericsson AB. 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. + + + + init + + + + + init.xml +
+ init + Coordination of System Startup + +

The init module is pre-loaded and contains the code for + the init system process which coordinates the start-up of + the system. The first function evaluated at start-up is + boot(BootArgs), where BootArgs is a list of command + line arguments supplied to the Erlang runtime system from + the local operating system. See + erl(1).

+

init reads the boot script which contains instructions on + how to initiate the system. See + script(4) for more + information about boot scripts.

+

init also contains functions to restart, reboot, and stop + the system.

+ + + + boot(BootArgs) -> void() + Start the Erlang runtime system + + BootArgs = [binary()] + + +

Starts the Erlang runtime system. This function is called + when the emulator is started and coordinates system start-up.

+

BootArgs are all command line arguments except + the emulator flags, that is, flags and plain arguments. See + erl(1).

+

init itself interprets some of the flags, see + Command Line Flags below. + The remaining flags ("user flags") and plain arguments are + passed to the init loop and can be retrieved by calling + get_arguments/0 and get_plain_arguments/0, + respectively.

+ + + + get_args() -> [Arg] + Get all non-flag command line arguments + + Arg = atom() + + +

Returns any plain command line arguments as a list of atoms + (possibly empty). It is recommended that + get_plain_arguments/1 is used instead, because of + the limited length of atoms.

+ + + + get_argument(Flag) -> {ok, Arg} | error + Get the values associated with a command line user flag + + Flag = atom() + Arg = [Values] +  Values = [string()] + + +

Returns all values associated with the command line user flag + Flag. If Flag is provided several times, each + Values is returned in preserved order.

+ 
+% erl -a b c -a d
+...
+1> init:get_argument(a).
+{ok,[["b","c"],["d"]]}
+

There are also a number of flags, which are defined + automatically and can be retrieved using this function:

+ + root + +

The installation directory of Erlang/OTP, $ROOT.

+ 
+2> init:get_argument(root).
+{ok,[["/usr/local/otp/releases/otp_beam_solaris8_r10b_patched"]]}
+ + progname + +

The name of the program which started Erlang.

+ 
+3> init:get_argument(progname).
+{ok,[["erl"]]}
+ + home + +

The home directory.

+ 
+4> init:get_argument(home).
+{ok,[["/home/harry"]]}
+ + +

Returns error if there is no value associated with + Flag.

+ + + + get_arguments() -> Flags + Get all command line user flags + + Flags = [{Flag, Values}] +  Flag = atom() +  Values = [string()] + + +

Returns all command line flags, as well as the system + defined flags, see get_argument/1.

+ + + + get_plain_arguments() -> [Arg] + Get all non-flag command line arguments + + Arg = string() + + +

Returns any plain command line arguments as a list of strings + (possibly empty).

+ + + + get_status() -> {InternalStatus, ProvidedStatus} + Get system status information + + InternalStatus = starting | started | stopping + ProvidedStatus = term() + + +

The current status of the init process can be + inspected. During system startup (initialization), + InternalStatus is starting, and + ProvidedStatus indicates how far the boot script has + been interpreted. Each {progress, Info} term + interpreted in the boot script affects ProvidedStatus, + that is, ProvidedStatus gets the value of Info.

+ + + + reboot() -> void() + Take down and restart an Erlang node smoothly + +

All applications are taken down smoothly, all code is + unloaded, and all ports are closed before the system + terminates. If the -heart command line flag was given, + the heart program will try to reboot the system. Refer + to heart(3) for more information.

+

To limit the shutdown time, the time init is allowed + to spend taking down applications, the -shutdown_time + command line flag should be used.

+ + + + restart() -> void() + Restart the running Erlang node + +

The system is restarted inside the running Erlang + node, which means that the emulator is not restarted. All + applications are taken down smoothly, all code is unloaded, + and all ports are closed before the system is booted again in + the same way as initially started. The same BootArgs + are used again.

+

To limit the shutdown time, the time init is allowed + to spend taking down applications, the -shutdown_time + command line flag should be used.

+ + + + script_id() -> Id + Get the identity of the used boot script + + Id = term() + + +

Get the identity of the boot script used to boot the system. + Id can be any Erlang term. In the delivered boot + scripts, Id is {Name, Vsn}. Name and + Vsn are strings.

+ + + + stop() -> void() + Take down an Erlang node smoothly + +

All applications are taken down smoothly, all code is + unloaded, and all ports are closed before the system + terminates. If the -heart command line flag was given, + the heart program is terminated before the Erlang node + terminates. Refer to heart(3) for more information.

+

To limit the shutdown time, the time init is allowed + to spend taking down applications, the -shutdown_time + command line flag should be used.

+ + + + stop(Status) -> void() + Take down an Erlang node smoothly + + Status = int()>=0 | string() + + +

All applications are taken down smoothly, all code is + unloaded, and all ports are closed before the system + terminates by calling halt(Status). If the + -heart command line flag was given, the heart + program is terminated before the Erlang node + terminates. Refer to heart(3) for more + information.

+

To limit the shutdown time, the time init is allowed + to spend taking down applications, the -shutdown_time + command line flag should be used.

+ + + + +
+ + Command Line Flags +

The support for loading of code from archive files is + experimental. The sole purpose of releasing it before it is ready + is to obtain early feedback. The file format, semantics, + interfaces etc. may be changed in a future release. The + -code_path_choice flag is also experimental.

 + +

The init module interprets the following command line + flags:

+ + + -- + +

Everything following -- up to the next flag is + considered plain arguments and can be retrieved using + get_plain_arguments/0.

+ + -code_path_choice Choice + +

This flag can be set to strict or relaxed. It + controls whether each directory in the code path should be + interpreted strictly as it appears in the boot script or if + init should be more relaxed and try to find a suitable + directory if it can choose from a regular ebin directory and + an ebin directory in an archive file. This flag is particular + useful when you want to elaborate with code loading from + archives without editing the boot script. See script(4) for more information + about interpretation of boot scripts. The flag does also have + a similar affect on how the code server works. See code(3).

+ + + -eval Expr + +

Scans, parses and evaluates an arbitrary expression + Expr during system initialization. If any of these + steps fail (syntax error, parse error or exception during + evaluation), Erlang stops with an error message. Here is an + example that seeds the random number generator:

+ 
+% erl -eval '{X,Y,Z}' = now(), random:seed(X,Y,Z).'
+

This example uses Erlang as a hexadecimal calculator:

+ 
+% erl -noshell -eval 'R = 16#1F+16#A0, io:format("~.16B~n", [R])' \\
+-s erlang halt
+BF
+

If multiple -eval expressions are specified, they + are evaluated sequentially in the order specified. + -eval expressions are evaluated sequentially with + -s and -run function calls (this also in + the order specified). As with -s and -run, an + evaluation that does not terminate, blocks the system + initialization process.

+ + -extra + +

Everything following -extra is considered plain + arguments and can be retrieved using + get_plain_arguments/0.

+ + -run Mod [Func [Arg1, Arg2, ...]] + +

Evaluates the specified function call during system + initialization. Func defaults to start. If no + arguments are provided, the function is assumed to be of arity + 0. Otherwise it is assumed to be of arity 1, taking the list + [Arg1,Arg2,...] as argument. All arguments are passed + as strings. If an exception is raised, Erlang stops with an + error message.

+

Example:

+ 
+% erl -run foo -run foo bar -run foo bar baz 1 2
+

This starts the Erlang runtime system and evaluates + the following functions:

+ +foo:start() +foo:bar() +foo:bar(["baz", "1", "2"]). +

The functions are executed sequentially in an initialization + process, which then terminates normally and passes control to + the user. This means that a -run call which does not + return will block further processing; to avoid this, use + some variant of spawn in such cases.

+ + -s Mod [Func [Arg1, Arg2, ...]] + +

Evaluates the specified function call during system + initialization. Func defaults to start. If no + arguments are provided, the function is assumed to be of arity + 0. Otherwise it is assumed to be of arity 1, taking the list + [Arg1,Arg2,...] as argument. All arguments are passed + as atoms. If an exception is raised, Erlang stops with an + error message.

+

Example:

+ 
+% erl -s foo -s foo bar -s foo bar baz 1 2
+

This starts the Erlang runtime system and evaluates + the following functions:

+ +foo:start() +foo:bar() +foo:bar([baz, '1', '2']). +

The functions are executed sequentially in an initialization + process, which then terminates normally and passes control to + the user. This means that a -s call which does not + return will block further processing; to avoid this, use + some variant of spawn in such cases.

+

Due to the limited length of atoms, it is recommended that + -run be used instead.

+ + +
+ +
+ Example + 
+% erl -- a b -children thomas claire -ages 7 3 -- x y
+...
+
+1> init:get_plain_arguments().
+["a","b","x","y"]
+2> init:get_argument(children).
+{ok,[["thomas","claire"]]}
+3> init:get_argument(ages).
+{ok, [["7","3"]]}
+4> init:get_argument(silly).
+error
+
+ +
+ SEE ALSO +

erl_prim_loader(3), + heart(3)

+
+ + diff --git a/erts/doc/src/make.dep b/erts/doc/src/make.dep new file mode 100644 index 0000000000..98bac78235 --- /dev/null +++ b/erts/doc/src/make.dep @@ -0,0 +1,32 @@ +# ---------------------------------------------------- +# >>>> Do not edit this file <<<< +# This file was automaticly generated by +# /home/gandalf/otp/bin/docdepend +# ---------------------------------------------------- + + +# ---------------------------------------------------- +# TeX files that the DVI file depend on +# ---------------------------------------------------- + +book.dvi: absform.tex alt_dist.tex book.tex crash_dump.tex \ + driver.tex driver_entry.tex epmd.tex erl.tex \ + erl_dist_protocol.tex erl_driver.tex erl_ext_dist.tex \ + erl_prim_loader.tex erl_set_memory_block.tex \ + erlang.tex erlc.tex erlsrv.tex erts_alloc.tex \ + escript.tex inet_cfg.tex init.tex match_spec.tex \ + part.tex ref_man.tex run_erl.tex start.tex \ + start_erl.tex tty.tex werl.tex zlib.tex + +# ---------------------------------------------------- +# Source inlined when transforming from source to LaTeX +# ---------------------------------------------------- + +book.tex: ref_man.xml + +# ---------------------------------------------------- +# Pictures that the DVI file depend on +# ---------------------------------------------------- + +book.dvi: erl_ext_fig.ps + diff --git a/erts/doc/src/match_spec.xml b/erts/doc/src/match_spec.xml new file mode 100644 index 0000000000..26480473d2 --- /dev/null +++ b/erts/doc/src/match_spec.xml @@ -0,0 +1,564 @@ + + + + +
+ + 19992009 + Ericsson AB. 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. + + + + Match specifications in Erlang + Patrik Nyblom + + + + + 1999-06-01 + PA1 + match_spec.xml +
+

A "match specification" (match_spec) is an Erlang term describing a + small "program" that will try to match something (either the + parameters to a function as used in the + BIF, or the objects in an ETS table.). + The match_spec in many ways works like a small function in Erlang, but is + interpreted/compiled by the Erlang runtime system to something much more + efficient than calling an Erlang function. The match_spec is also + very limited compared to the expressiveness of real Erlang functions.

+

Match specifications are given to the BIF to + execute matching of function arguments as well as to define some actions + to be taken when the match succeeds (the part). Match + specifications can also be used in ETS, to specify objects to be + returned from an call (or other select + calls). The semantics and restrictions differ slightly when using + match specifications for tracing and in ETS, the differences are + defined in a separate paragraph below.

+

The most notable difference between a match_spec and an Erlang fun is + of course the syntax. Match specifications are Erlang terms, not + Erlang code. A match_spec also has a somewhat strange concept of + exceptions. An exception (e.g., ) in the + part, + which resembles an Erlang guard, will generate immediate failure, + while an exception in the part, which resembles the body of an + Erlang function, is implicitly caught and results in the single atom + . +

+ +
+ Grammar +

A match_spec can be described in this informal grammar:

+ + MatchExpression ::= [ MatchFunction, ... ] + + MatchFunction ::= { MatchHead, MatchConditions, MatchBody } + + MatchHead ::= MatchVariable | | [ MatchHeadPart, ... ] + + MatchHeadPart ::= term() | MatchVariable | + MatchVariable ::= '$<number>' + + MatchConditions ::= [ MatchCondition, ...] | + MatchCondition ::= { GuardFunction } | + { GuardFunction, ConditionExpression, ... } + + BoolFunction ::= | | + | | | + | | | + | | | + | | | + | | | | + | + ConditionExpression ::= ExprMatchVariable | { GuardFunction } | + { GuardFunction, ConditionExpression, ... } | TermConstruct + + ExprMatchVariable ::= MatchVariable (bound in the MatchHead) | + | + TermConstruct = {{}} | {{ ConditionExpression, ... }} | + | [ConditionExpression, ...] | NonCompositeTerm | Constant + + NonCompositeTerm ::= term() (not list or tuple) + + Constant ::= {, term()} + + GuardFunction ::= BoolFunction | | + | | | | + | | | | + | | | | + | | | | + | | | ']]> | + =']]> | | | | + | | | | + + MatchBody ::= [ ActionTerm ] + + ActionTerm ::= ConditionExpression | ActionCall + + ActionCall ::= {ActionFunction} | + {ActionFunction, ActionTerm, ...} + + ActionFunction ::= | + | | + | | | + | | | + | | | + + +
+ +
+ Function descriptions + +
+ Functions allowed in all types of match specifications +

The different functions allowed in work like this: +

+

is_atom, is_constant, is_float, is_integer, is_list, is_number, is_pid, is_port, is_reference, is_tuple, is_binary, is_function: Like the corresponding guard tests in + Erlang, return or . +

+

is_record: Takes an additional parameter, which SHALL + be the result of )]]>, + like in . +

+

'not': Negates its single argument (anything other + than gives ). +

+

'and': Returns if all its arguments + (variable length argument list) evaluate to , else + . Evaluation order is undefined. +

+

'or': Returns if any of its arguments + evaluates to . Variable length argument + list. Evaluation order is undefined. +

+

andalso: Like , but quits evaluating its + arguments as soon as one argument evaluates to something else + than true. Arguments are evaluated left to right. +

+

orelse: Like , but quits evaluating as soon + as one of its arguments evaluates to . Arguments are + evaluated left to right. +

+

'xor': Only two arguments, of which one has to be true + and the other false to return ; otherwise + returns false. +

+

abs, element, hd, length, node, round, size, tl, trunc, '+', '-', '*', 'div', 'rem', 'band', 'bor', 'bxor', 'bnot', 'bsl', 'bsr', '>', '>=', '<', '=<', '=:=', '==', '=/=', '/=', self: Work as the corresponding Erlang bif's (or + operators). In case of bad arguments, the result depends on + the context. In the part of the + expression, the test fails immediately (like in an Erlang + guard), but in the , exceptions are implicitly + caught and the call results in the atom .

+
+ +
+ Functions allowed only for tracing +

is_seq_trace: Returns if a sequential + trace token is set for the current process, otherwise . +

+

set_seq_token: Works like + , but returns on success + and on error or bad argument. Only allowed in the + part and only allowed when tracing. +

+

get_seq_token: Works just like + , and is only allowed in the + part when tracing. +

+

message: Sets an additional message appended to the + trace message sent. One can only set one additional message in + the body; subsequent calls will replace the appended message. As + a special case, disables sending of + trace messages ('call' and 'return_to') + for this function call, just like if the match_spec had not matched, + which can be useful if only the side effects of + the are desired. + Another special case is which + sets the default behavior, as if the function had no match_spec, + trace message is sent with no extra + information (if no other calls to are placed + before , it is in fact a "noop"). +

+

Takes one argument, the message. Returns and can + only be used in the part and when tracing. +

+

return_trace: Causes a trace + message to be sent upon return from the current function. + Takes no arguments, returns and can only be used + in the part when tracing. + If the process trace flag + is active the trace message is inhibited. +

+

NOTE! If the traced function is tail recursive, this match + spec function destroys that property. + Hence, if a match spec executing this function is used on a + perpetual server process, it may only be active for a limited + time, or the emulator will eventually use all memory in the host + machine and crash. If this match_spec function is inhibited + using the process trace flag + tail recursiveness still remains. +

+

exception_trace: Same as return_trace, + plus; if the traced function exits due to an exception, + an trace message is generated, + whether the exception is caught or not. +

+

process_dump: Returns some textual information about + the current process as a binary. Takes no arguments and is only + allowed in the part when tracing. +

+

enable_trace: With one parameter this function turns + on tracing like the Erlang call , where is the parameter to + . With two parameters, the first parameter + should be either a process identifier or the registered name of + a process. In this case tracing is turned on for the designated + process in the same way as in the Erlang call , where P1 is the first and P2 is the second + argument. The process gets its trace messages sent to the same + tracer as the process executing the statement uses. + can not be one of the atoms , or + (unless, of course, they are registered names). + can not be nor + . + Returns and may only be used in + the part when tracing. +

+

disable_trace: With one parameter this function + disables tracing like the Erlang call , where is the parameter to + . With two parameters it works like the + Erlang call , where P1 can + be either a process identifier or a registered name and is given + as the first argument to the match_spec function. + can not be nor + . Returns + and may only be used in the part + when tracing. +

+

trace: With two parameters this function takes a list + of trace flags to disable as first parameter and a list + of trace flags to enable as second parameter. Logically, the + disable list is applied first, but effectively all changes + are applied atomically. The trace flags + are the same as for not including + but including . If a + tracer is specified in both lists, the tracer in the + enable list takes precedence. If no tracer is specified the + same tracer as the process executing the match spec is + used. With three parameters to this function the first is + either a process identifier or the registered name of a + process to set trace flags on, the second is the disable + list, and the third is the enable list. Returns + if any trace property was changed for the + trace target process or if not. It may only + be used in the part when tracing. +

+

caller: + Returns the calling function as a tuple {Module, + Function, Arity} or the atom if the calling + function cannot be determined. May only be used in the + part when tracing. +

+

Note that if a "technically built in function" (i.e. a + function not written in Erlang) is traced, the + function will sometimes return the atom . The calling + Erlang function is not available during such calls. +

+

display: For debugging purposes only; displays the + single argument as an Erlang term on stdout, which is seldom + what is wanted. Returns and may only be used in the + part when tracing. +

+

+get_tcw: + Takes no argument and returns the value of the node's trace + control word. The same is done by + . +

+

The trace control word is a 32-bit unsigned integer intended for + generic trace control. The trace control word can be tested and + set both from within trace match specifications and with BIFs. + This call is only allowed when tracing. +

+

+set_tcw: + Takes one unsigned integer argument, sets the value of + the node's trace control word to the value of the argument + and returns the previous value. The same is done by + . It is only + allowed to use in the part + when tracing. +

+

silent: + Takes one argument. If the argument is , the call + trace message mode for the current process is set to silent + for this call and all subsequent, i.e call trace messages + are inhibited even if is called in the + part for a traced function. +

+

This mode can also be activated with the flag + to . +

+

If the argument is , the call trace message mode + for the current process is set to normal (non-silent) for + this call and all subsequent. +

+

If the argument is neither nor , + the call trace message mode is unaffected.

+
+

Note that all "function calls" have to be tuples, + even if they take no arguments. The value of is + the atom() , but the value of is + the pid() of the current process.

+
+ +
+ Variables and literals +

Variables take the form ']]> where + ]]> is an integer between 0 (zero) and + 100000000 (1e+8), the behavior if the number is outside these + limits is undefined. In the part, the special + variable matches anything, and never gets bound (like + in Erlang). In the + parts, no unbound variables are allowed, why is + interpreted as itself (an atom). Variables can only be bound in + the part. In the and + parts, only variables bound previously may + be used. As a special case, in the + parts, the variable + expands to the whole expression which matched the + (i.e., the whole parameter list to the possibly + traced function or the whole matching object in the ets table) + and the variable expands to a list + of the values of all bound variables in order + (i.e. ). +

+

In the part, all literals (except the variables + noted above) are interpreted as is. In the + parts, however, the + interpretation is in some ways different. Literals in the + can either be written as is, + which works for all literals except tuples, or by using the + special form , where is any Erlang + term. For tuple literals in the match_spec, one can also use + double tuple parentheses, i.e., construct them as a tuple of + arity one containing a single tuple, which is the one to be + constructed. The "double tuple parenthesis" syntax is useful to + construct tuples from already bound variables, like in + . Some examples may be needed: +

+ + + Expression\011\011 + Variable bindings\011\011 + Result\011 + + + {{'$1','$2'}}\011\011 + '$1' = a, '$2' = b + {a,b} + + + {const, {'$1', '$2'}}\011 + doesn't matter + {'$1', '$2'} + + + a\011\011\011 + doesn't matter\011\011\011 + a + + + '$1'\011\011\011 + '$1' = []\011\011\011 + [] + + + ['$1']\011\011\011 + '$1' = []\011\011\011 + [[]] + + + [{{a}}]\011\011\011 + doesn't matter + [{a}] + + + 42\011\011\011 + doesn't matter + 42 + + + "hello"\011\011\011 + doesn't matter + "hello" + + + $1\011\011\011 + doesn't matter + 49 (the ASCII value for the character '1') + + Literals in the MatchCondition/MatchBody parts of a match_spec +
+
+ +
+ Execution of the match +

The execution of the match expression, when the runtime system + decides whether a trace message should be sent, goes as follows: +

+

For each tuple in the list and while no + match has succeeded:

+ + Match the part against the arguments to the + function, + binding the ']]> variables (much like in + ). + If the cannot match the arguments, the match fails. + + Evaluate each (where only + ']]> variables previously bound in the + can occur) and expect it to return the atom + . As soon as a condition does not evaluate to + , the match fails. If any BIF call generates an + exception, also fail. + + + + If the match_spec is executing when tracing:

+ Evaluate each in the same way as the + , but completely ignore the return + values. Regardless of what happens in this part, the match has + succeeded. + If the match_spec is executed when selecting objects from an ETS table:

+ Evaluate the expressions in order and return the value of + the last expression (typically there is only one expression + in this context) + + + +
+ +
+ Differences between match specifications in ETS and tracing +

ETS match specifications are there to produce a return + value. Usually the expression contains one single + which defines the return value without having + any side effects. Calls with side effects are not allowed in the + ETS context.

+

When tracing there is no return value to produce, the + match specification either matches or doesn't. The effect when the + expression matches is a trace message rather then a returned + term. The 's are executed as in an imperative + language, i.e. for their side effects. Functions with side effects + are also allowed when tracing.

+

In ETS the match head is a (or a single match + variable) while it is a list (or a single match variable) when + tracing.

+
+ +
+ Examples +

Match an argument list of three where the first and third arguments + are equal:

+ +

Match an argument list of three where the second argument is + a number greater than three:

+ ', '$1', 3}], + []}] + ]]> +

Match an argument list of three, where the third argument + is a tuple containing argument one and two or a list + beginning with argument one and two (i. e. or + ): +

+ +

The above problem may also be solved like this:

+ +

Match two arguments where the first is a tuple beginning with + a list which in turn begins with the second argument times + two (i. e. [{[4,x],y},2] or [{[8], y, z},4])

+ +

Match three arguments. When all three are equal and are + numbers, append the process dump to the trace message, else + let the trace message be as is, but set the sequential trace + token label to 4711.

+ +

As can be noted above, the parameter list can be matched + against a single or an . To replace the + whole + parameter list with a single variable is a special case. In all + other cases the has to be a proper list. +

+

Match all objects in an ets table where the first element is + the atom 'strider' and the tuple arity is 3 and return the whole + object.

+ +

Match all objects in an ets table with arity > 1 and the first + element is 'gandalf', return element 2.

+ =',{size, '$1'},2}], + [{element,2,'$1'}]}] + ]]> +

In the above example, if the first element had been the key, + it's much more efficient to match that key in the + part than in the part. The search space of + the tables is restricted with regards to the so + that only objects with the matching key are searched. +

+

Match tuples of 3 elements where the second element is either + 'merry' or 'pippin', return the whole objects.

+ +

The function can be useful for testing + complicated ets matches.

+
+ + diff --git a/erts/doc/src/notes.xml b/erts/doc/src/notes.xml new file mode 100644 index 0000000000..2252358e0d --- /dev/null +++ b/erts/doc/src/notes.xml @@ -0,0 +1,5439 @@ + + + + +
+ + 20042009 + Ericsson AB. 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. + + + + ERTS Release Notes + otp_appnotes + nil + nil + nil + notes.xml +
+

This document describes the changes made to the ERTS application.

+ +
Erts 5.7.4 + +
Fixed Bugs and Malfunctions + + +

+ An insufficient stack allocation was made when reading + CPU information on BSD operating systems. (Thanks Michael + Turner and Akira Kitada)

+

+ Own Id: OTP-8207

+ + +

+ A bug when supplying an argument without a dash directly + after the program name when starting erlang could prevent + distribution to start. This is now corrected.

+

+ Own Id: OTP-8209

+ + +

+ A ticker process could potentially be blocked + indefinitely trying to send a tick to a node not + responding. If this happened, the connection would not be + brought down as it should.

+

+ Own Id: OTP-8218

+ + +

+ Using certain firewalls (i.e. MS IAS Client and certain + versions of COMODO) could expose an undocumented + behaviour in the Win32 socket interface causing the name + resolution calls to hang infinitely. This is now worked + around by adding possibilities for port programs under + Windows to use overlapped I/O on their standard + input/output file handles.

+

+ Own Id: OTP-8230

+ + +

+ Fixed bug on ETS tables with write_concurrency. + The emulator could crash when doing a select or + match with a bound key without finding any object.

+

+ Own Id: OTP-8242

+ + +

The information-request / + information-response, and + group-leader-change-request / + group-leader-changed-response signal pairs + described below did not always adhere to the signal order + guarantees of Erlang's signal model in the runtime system + with SMP support. These signals could for example + sometimes pass exit signals.

+

The following BIFs behaviors can be modeled as if an + asynchronous information-request signal is sent to + Pid. If Pid is alive, it responds with an + asynchronous information-response signal; + otherwise, the runtime system responds with a + no-such-process signal. When the response is + received, the caller transforms it into the result of the + BIF.

is_process_alive(Pid) + erlang:process_display(Pid, Type) + process_info(Pid) + process_info(Pid, ItemSpec) +

When Pid resides on the same node as the caller + of group_leader(GroupLeader, Pid), the + group_leader/2 BIFs behavior can be modeled as if + an asynchronous group-leader-change-request signal + is sent to Pid. If Pid is alive, it + responds with an asynchronous + group-leader-changed-response signal; otherwise, + the runtime system responds with a no-such-process + signal. When the response is received, the caller + transforms it into the result of the BIF. The distributed + case which only consists of an asynchronous + group-leader-change-request signal and no response + is not effected.

+

+ Own Id: OTP-8245

+ + +

+ Errors in the system_profile documentation has + been corrected.

+

+ Own Id: OTP-8257

+ + +

+ Low watermark socket option modified high watermark + instead of low watermark in the inet_driver. (Thanks to + Feng Yu and Tuncer Ayaz)

+

+ Own Id: OTP-8279

+ + +

+ A race condition could cause the runtime system with SMP + support to end up in a completely unresponsive state.

+

+ Own Id: OTP-8297

+ + +
+ + +
Improvements and New Features + + +

+ The use of pthread_cond_timedwait() have been + completely removed from the runtime system. This since + its behavior is unpredictable when the system clock is + suddenly changed. The previous use of it was harmless.

+

+ Own Id: OTP-8193

+ + +

+ The documentation is now built with open source tools + (xsltproc and fop) that exists on most platforms. One + visible change is that the frames are removed.

+

+ Own Id: OTP-8201

+ + +

+ A new garbage collecting strategy for binaries which is + more aggressive than the previous implementation. + Binaries now has a virtual binary heap tied to each + process. When binaries are created or received to a + process it will check if the heap limit has been reached + and if a reclaim should be done. This imitates the + behavior of ordinary Erlang terms. The virtual heaps are + grown and shrunk like ordinary heaps. This will lessen + the memory footprint of binaries in a system.

+

+ Own Id: OTP-8202

+ + +

+ The ErlDrvTermData term types used by + driver_output_term() and driver_send_term() + have been extended with the term types + ERL_DRV_INT64, and ERL_DRV_UINT64 for + passing 64-bit integers. Also the 64-bit integer data + types ErlDrvSInt64 and ErlDrvUInt64 have + been introduced.

+

+ For more information see the erl_driver(3) + documentation.

+

+ Own Id: OTP-8205

+ + +

+ [escript] The restriction that the first line in escripts + must begin with #! has been removed.

+

+ [escript] Some command line options to the escript + executable has now been documented. For example you can + run an escript in the debugger by just adding a command + line option.

+

+ [escript] The documentation of the escript header syntax + has been clarified. For example the header is optional. + This means that it is possible to directly "execute" + .erl, .beam and.zip files.

+

+ Own Id: OTP-8215

+ + +

+ The instruction for building OTP on Windows was outdated + and incomplete, the document is updated.

+

+ Also the otp_build script required windows drives to show + up in Cygwin using the /cygdrive prefix. That requirement + is now removed.

+

+ Own Id: OTP-8219

+ + +

+ A module can have native implemented functions (NIFs) + that are dynamically loaded by calling + erlang:load_nif/2. This is an experimental feature + that is not yet intended for production systems. It is + released with intention to get some early feedback on the + interfaces before they are carved in stone.

+

+ Own Id: OTP-8220

+ + +

+ The float/1 BIF would always force a garbage + collection. The BIFs size/1, byte_size/1, + bit_size/1, abs/1, and round/1 would + force a garbage-collection if the result was not a + sufficiently small integer.

+

+ Own Id: OTP-8221

+ + +

+ The erlang:port_command/3 + BIF has been added. erlang:port_command/3 is + currently not auto imported, but it is planned to be auto + imported in OTP R14. For more information see the + erlang(3) + documentation.

+

+ Own Id: OTP-8225

+ + +

+ 'configure --enable-darwin-64bit' would fail if + Snow Leopard had been booted with the 64-bit kernel. + (Thanks to Ryan M. Graham.)

+

+ Own Id: OTP-8236

+ + +
+ +
+ +
Erts 5.7.3 + +
Fixed Bugs and Malfunctions + + +

+ On Windows, open_port({spawn,Command},Opts) could not run + executables with spaces in the path or filename, + regardless of quoting efforts. While + open_port({spawn_executable,Exec},Opts) can run any + executable, it was still impossible to use 'spawn' to do + the same thing. This is now corrected.

+

+ Own Id: OTP-8055

+ + +

+ The scheduler bind type processor_spread spread + schedulers too much on large NUMA systems.

+

+ The new scheduler bind type spread spreads + schedulers as much as possible, and behaves as + processor_spread previously did. For more + information see the documentation of the +sbt + command line argument in the erl(1) documentation, + and the documentation of + erlang:system_flag(scheduler_bind_type, + SchedulerBindType).

+

+ Own Id: OTP-8063

+ + +

+ Automatically detected CPU topology on Linux system could + erroneously contain logical processors with -1 as + identifiers. This happened when + sysconf(_SC_NPROCESSORS_CONF) returned a value + larger than the amount of logical processors found.

+

+ Own Id: OTP-8064

+ + +

+ When the minimal term [] (end of list) was sent as the + complete message to a process on another node, and + received there, it could not be decoded. This bug is now + corrected. Fortunately [] is uncommon as the complete + message in real applications but it is a serious bug + anyway.

+

+ Own Id: OTP-8092

+ + +

A bug when the floating point exception pointer was + not initialized has been corrected. It manifested itself + on CentOS 5.1 sometimes when a floating point value was + sent to a remote node. Bug reported and patch suggested + by David Reiss, confirmed by Mikael Pettersson.

+

Some build problems on IRIX was also corrected. + Problem reported by Patrick Baggett, patch by Mikael + Pettersson.

+

+ Own Id: OTP-8095

+ + +

+ A terminating process could erroneously unregister a name + for another process. This could occur under the following + conditions: The name of the terminating process was + unregistered and then registered for another process + simultaneously as the process that first had the name was + terminating.

+

+ Own Id: OTP-8099 Aux Id: seq11344

+ + +

+ Running erlc in a very deep directory (with a path length + of more 256 or more characters) would cause the emulator + to crash in a call to list_to_atom/1. (Thanks to + Chris Newcombe.)

+

+ Own Id: OTP-8124

+ + +

+ A deadlock of the runtime system could occur when + unregistering the name of a port.

+

+ Own Id: OTP-8145

+ + +

+ Makefile.in has been updated to use the LDFLAGS + environment variable (if set). (Thanks to Davide + Pesavento.)

+

+ Own Id: OTP-8157

+ + +

+ The pthread rwlock implemention on Linux could cause + starvation of writers. We, therefore, now use our own + rwlock implementation on Linux.

+

+ Own Id: OTP-8158

+ + +

+ Open source Erlang builds are updated to work well on + Snow Leopard (MacOS X 10.6)

+

+ Own Id: OTP-8168

+ + +

+ A call to erlang:system_info(schedulers_online) + could end up in an infinite loop. This happened if the + amount of schedulers was larger than one, the amount of + schedulers online was one, and someone was blocking + multi-scheduling.

+

+ Own Id: OTP-8169

+ + +

+ An error in erlang:system_profile/2 could cause + timestamped messages to arrive out of order in the SMP + case. This has now been fixed.

+

+ Own Id: OTP-8171

+ + +

+ binary_to_atom/2 and + binary_to_existing_atom/2 would leak memory if the + binary contained unaligned data.

+

+ Own Id: OTP-8192

+ + +

+ The async thread pool in the runtime system without SMP + support used a memory allocator that was not thread safe + for async jobs.

+

+ Own Id: OTP-8194

+ + +
+ + +
Improvements and New Features + + +

+ Processor internal NUMA nodes are now supported in the + ERTS internal CPU topology representation. For more + information see the documentation of the +sct + command line argument in the erl(1) documentation, + and the documentation of + erlang:system_info(cpu_topology).

+

+ Own Id: OTP-8041

+ + +

+ Documentation for ets improved about concurrency.

+

+ Own Id: OTP-8050

+ + +

+ Emulator flags in an escript were earlier inherited to + emulators started from from the emulator running the + escript. For example when an escript invoked + os:cmd("erl"), the new emulator were given + erroneous emulator flags. This bug has now been fixed

+

+ Escript filenames may now contain dots.

+

+ Own Id: OTP-8060

+ + +

+ Made some BIFs non-recursive (relational operators,hash + and phash) to limit internal stack usage.

+

+ Own Id: OTP-8065

+ + +

+ Fixed Windows specific bug in erl_prim_loader. Now it + handles the root directory (e.g. c:/) better. This bug + affected the directory listing in the debugger.

+

+ Own Id: OTP-8080

+ + +

+ A TCP socket with option {packet,4} could crash + the emulator if it received a packet header with a very + large size value (>2Gb). The same bug caused + erlang:decode_packet/3 to return faulty values. + (Thanks to Georgos Seganos.)

+

+ Own Id: OTP-8102

+ + +

+ The maximum size of the export table has been raised from + 65536 to 524288 entries.

+

+ Own Id: OTP-8104 Aux Id: seq11345

+ + +

+ The file module has now a read_line/1 function similar to + the io:get_line/2, but with byte oriented semantics. The + function file:read_line/1 works for raw files as well, + but for good performance it is recommended to use it + together with the 'read_ahead' option for raw file + access.

+

+ Own Id: OTP-8108

+ + +

+ Fixed bug causing emulator crash when reading a term in + external format containing a corrupt list with a negative + length.

+

+ Own Id: OTP-8117

+ + +

+ New emulator flag +sss, to set stack size of + scheduler threads.

+

+ Own Id: OTP-8119

+ + +

+ The Windows utility Erlsrv, run in interactive mode now + accepts options for registering internal service name and + description field of Windows registry database.

+

+ Own Id: OTP-8132

+ + +

+ erlang:demonitor(Mon, [flush]) has been optimized. + Previously it always searched the message queue of the + caller for a 'DOWN' message. Current + implementation only search the message queue when + necessary. It is quite common that the search is not + necessary.

+

+ A new option info has been added to + erlang:demonitor/2. For more information see the + erlang(3) documentation.

+

+ Own Id: OTP-8143

+ + +

+ I/O tasks could unnecessarily be rescheduled. This was + harmless, but not useful work.

+

+ Own Id: OTP-8148

+ + +

+ Minor improvements of erlang:memory/[1,2].

+

+ Own Id: OTP-8152

+ + +

+ New configuration option to enable use of shared zlib.

+

+ Own Id: OTP-8155

+ + +

+ Fixed smp bug in ETS that could cause emulator crash when + table with more than 1000 objects accessed by several + processes, including calls to variants of select + or match combined with concurrent object deletion.

+

+ Own Id: OTP-8166 Aux Id: seq11392

+ + +

+ The code path interpretation is now more relaxed. The + flag -code_path_choice now defaults to relaxed instead of + strict. See the documentation of code and init for more + info.

+

+ Own Id: OTP-8170

+ + +

+ Load balancing of run queues and check for I/O are + triggered more often than before in situations where + processes are scheduled often but are doing very little + work each time they execute.

+

+ Own Id: OTP-8172

+ + +

+ Call tracing binary comprehensions would cause an + emulator crash. (Thanks to Paul Mineiro.)

+

+ Own Id: OTP-8179

+ + +

+ binary_to_term/1 would crash the emulator instead + of generating a badarg exception when given + certain invalid terms. (Thanks to Scott Lystig Fritchie.)

+

+ Own Id: OTP-8180

+ + +
+ +
+ +
Erts 5.7.2 + +
Fixed Bugs and Malfunctions + + +

+ Crash dumps should now cause less problems for the + crashdump_viewer application. (For processes where arity + was non-zero, the arguments are now longer printed - they + used to be printed in a format that was not parseable.)

+

+ Own Id: OTP-7472 Aux Id: seq11019, 11292

+ + +

+ Processes could potentially get stuck on an offline + scheduler.

+

+ Own Id: OTP-7990

+ + +

+ binary_to_atom/2 and + binary_to_existing_atom/2 could leak memory if + they caused a badarg exception.

+

+ Own Id: OTP-7997

+ + +

+ A process could under very rare circumstances erroneously + be resumed.

+

+ Own Id: OTP-8000

+ + +

+ Load balancing between schedulers could under rare + circumstances cause an emulator crash.

+

+ Own Id: OTP-8008

+ + +

+ erlang:memory(processes_used) always returned + 0 instead of the correct value. (Thanks to Geoff + Cant)

+

+ Own Id: OTP-8022

+ + +
+ + +
Improvements and New Features + + +

+ Major improvements of the Erlang distribution for Erlang + runtime systems with SMP support. Previously distribution + port locks were heavily contended, and all encoding and + decoding for a specific distribution channel had to be + done in sequence. Lock contention due to the distribution + is now negligible and both encoding and decoding of + Erlang messages can be done in parallel.

+

+ The old atom cache protocol used by the Erlang + distribution has been dropped since it effectively + prevented all parallel encoding and decoding of messages + passed over the same distribution channel.

+

+ A new atom cache protocol has been introduced which + isolates atom cache accesses and makes parallel encoding + and decoding of messages passed over the same + distribution channel possible. The new atom cache + protocol also use an atom cache size 8 times larger than + before. The new atom cache protocol is documented in the + ERTS users guide.

+

+ Erlang messages received via the distribution are now + decoded by the receiving Erlang processes without holding + any distribution channel specific locks. Erlang messages + and signals sent over the distribution are as before + encoded by the sending Erlang process, but now without + holding any distribution channel specific locks during + the encoding. That is, both encoding and decoding can be + and are done in parallel regardless of distribution + channel used.

+

+ The part that cannot be parallelized is the atom cache + updates. Atom cache updates are therefore now scheduled + on the distribution port. Since it is only one entity per + distribution channel doing this work there is no lock + contention due to the atom cache updates.

+

+ The new runtime system does not understand the old atom + cache protocol. New and old runtime systems can however + still communicate, but no atom cache will be used.

+

+ Own Id: OTP-7774

+ + +

+ Fixed a bug that caused error logging from + driver_select sometimes with additional symptoms + such as failing IP communications or even an emulator + crash.

+

+ Own Id: OTP-7898 Aux Id: seq11304

+ + +

+ Improved SMP concurrency for ETS tables. Several mutating + operations can now be performed truly concurrent on + different records of the same table. To support this, the + table has to be created with option + write_concurrency, as it is achieved at the + expense of some execution and memory overhead. + ets:select and select_count has also been + improved for all tables to not acquire exclusive table + lock during the iteration.

+

+ Own Id: OTP-7922

+ + +

+ erl (that is erl.exe and dyn_erl) and erlexec has been + made more dynamic so no hard coded paths needs to added + at installation time to erl (that is erl.ini and erl). + Reltool will make use of this in a future release.

+

+ Own Id: OTP-7952

+ + +

+ Added functionality to get higher resolution timestamp + from system. The erlang:now function returns a timestamp + that's not always consistent with the actual operating + system time (due to resilience against large time changes + in the operating system). The function os:timestamp/0 is + added to get a similar timestamp as the one being + returned by erlang:now, but untouched by Erlangs time + correcting and smoothing algorithms. The timestamp + returned by os:timestamp is always consistent with the + operating systems view of time, like the calendar + functions for getting wall clock time, but with higher + resolution. Example of usage can be found in the os + manual page.

+

+ Own Id: OTP-7971

+ + +

+ Two new options are added to open_port - spawn_executable + which runs external executables in a controlled way, and + spawn_driver which only opens port to loaded Erlang + drivers. See the erlang manual page for details.

+

+ Own Id: OTP-7995

+ + +

+ New functionality in ETS to transfer the ownership of a + table. A table can either change owner be declaring an + "heir", another process that will inherit the table if + the owner terminates. A table can also change owner by + calling a new function ets:give_away.

+

+ Own Id: OTP-8006

+ + +

+ Updates to Tilera build environment.

+

+ Own Id: OTP-8009

+ + +

+ A stack trace was unnecessarily saved during process + termination.

+

+ Own Id: OTP-8014

+ + +

+ User defined CPU topology and scheduler bind type can now + be set from the command line when starting an emulator. + For more information see the documentation of the + +sct, and the +sbt emulator flags in the + erl(1) documentation.

+

+ The CPU topologies returned from + erlang:system_info/1 and + erlang:system_flag/2 now always contain the + processor level, also when not strictly necessary.

+

+ Own Id: OTP-8030

+ + +

+ Various fixes in ETS: ets:first could return a + deleted key in a fixated table. ets:lookup could + return objects out of order if a deleted object was + re-inserted into a fixed bag. ets:delete_object + could fail to delete duplicate objects in a + duplicate_bag.

+

+ Own Id: OTP-8040

+ + +
+ +
+ +
Erts 5.7.1 + +
Fixed Bugs and Malfunctions + + +

+ Fixed a bug on Windows that could make + gen_tcp:send hang trying to send an iolist of more + than 16 binaries.

+

+ Own Id: OTP-7816

+ + +

+ The runtime system could under rare circumstances crash + during load balancing.

+

+ Own Id: OTP-7908 Aux Id: otp-7500

+ + +

+ run_erl uses fallback if Unix98 pseudo-terminal is + not present on host.

+

+ Own Id: OTP-7916 Aux Id: seq11249

+ + +

+ A message buffer memory leak in the runtime system + without smp support has been fixed.

+

+ Own Id: OTP-7941

+ + +

Attempting to append a binary of 16Mb or greater to + another binary using the bit syntax would cause a + system_limit exception. There was also several + cases when constructing binaries when a badarg + exception was generated when it should have been + system_limit.

+

+ Own Id: OTP-7942

+ + +

+ The runtime system with SMP support failed to terminate + the caller of link(RemotePid) properly, if + RemotePid was the pid of a process on an + unreachable node. The calling process was in this case + marked as exiting, but never terminated.

+

+ Own Id: OTP-7946

+ + +
+ + +
Improvements and New Features + + +

+ Rudimentary support for cross compiling is added to the + source release. The support is still in its infancy and + has only been used to cross compile on Linux for a + different cpu architecture and a different Linux version, + but should be extendible to support other platforms as + well. The cross configuration files with examples are + placed in $ERL_TOP/xcomp/. View README.xcomp and run + $ERL_TOP/otp_build -help for further information.

+

+ Own Id: OTP-7854

+ + +

The escape sequence \{ which was given a new + interpretation in R13A has retained its old meaning (the + ASCII code for {), which means that codes greater + than 255 have to be stated using hexadecimal characters + (for example, \x{AAA}). The escape sequence + \xH where H is a hexadecimal character followed by + something else but a hexadecimal character is no longer + valid (incompatibility with R13A). Character codes less + than 256 can be stated using two hexadecimal characters + (for example, \x0D).

+

+ Own Id: OTP-7891 Aux Id: OTP-7855

+ + +

The term_to_binary/1 BIF used to be implemented + with recursive C code, which could cause the Erlang + emulator to terminate because of a stack overflow.

+

Also fixed some minor issues in + term_to_binary/1 and binary_to_term/1 + pointed out by Matthew Dempsky.

+

+ Own Id: OTP-7894

+ + +

+ Several glitches and performance issues in the Unicode + and I/O-system implementation of R13A have been + corrected.

+

+ Own Id: OTP-7896 Aux Id: OTP-7648 OTP-7887

+ + +

+ Minor documentation improvements of the + scheduler_bind_type argument of + erlang:system_flag/2, and the + scheduler_bind_type, and the + scheduler_bindings arguments of + erlang:system_info/1.

+

+ Own Id: OTP-7901 Aux Id: OTP-7777

+ + +

+ There is a new BIF erlang:make_tuple/3.

+

+ Own Id: OTP-7913

+ + +
+ +
+ + +
Erts 5.7 + +
Fixed Bugs and Malfunctions + + +

OpenSource:

+

FreeBSD leap-seconds are handled according to patch + submitted by OpenSource user Kenji Rikitake. No test case + covers this functionality (unsupported platform).

+

+ Own Id: OTP-7609

+ + +

+ A corrected bug in ets for bag and + duplicate_bag. A delete/2 or + lookup_element/3 could miss objects in a fixed + table if one or more objects with the same key had + already been deleted.

+

+ Own Id: OTP-7665

+ + +

+ A new driver call-back stop_select is introduced + to allow drivers to de-select and then close a file + descriptor in a safe way in a SMP emulator. The old way + was not strictly according to posix standard and could in + some rare cases lead to unexpected behavior. A new flag + ERL_DRV_USE can be passed to + driver_select() to tell it that the descriptor + should be closed. stop_select is then called when + it is safe to do so. Old drivers will however still work + as before.

+

+ Own Id: OTP-7670

+ + +

+ A bug fixed for TCP sockets with option + {packet,http}. An HTTP request with an absolute + URI was returned with a corrupt path string. This bug did + only exist in R12B-4 and R12B-5.

+

+ Own Id: OTP-7682 Aux Id: OTP-7647

+ + +

+ run_erl did in some cases fail to extract control + sequences from to_erl (like: winsize=X,Y) and did instead + send them to be interpreted by the erlang shell.

+

+ Own Id: OTP-7688

+ + +

+ A bug in the installer on Windows not updating file + associations properly is now corrected.

+

+ Own Id: OTP-7746

+ + +

More space than necessary could be allocated in + binaries when appending to a binary (also in a binary + comprehension) and the data appended did not consist of + wholes bytes (e.g. 13 bits).

+

+ Own Id: OTP-7747

+ + +

+ The gen_sctp option sctp_peer_addr_params, + #sctp_paddrparams{address={IP,Port} was erroneously + decoded in the inet driver. This bug has now been + corrected.

+

+ Own Id: OTP-7755

+ + +

+ Outstanding async driver jobs leaked memory if the + issuing port died before the async jobs completed.

+

+ Own Id: OTP-7784

+ + +

A bug in the dynamic library loading affecting, among + others, OpenSolaris is now corrected. (Thanks to Paul + Fisher.)

+

+ Own Id: OTP-7796

+ + +

+ run_erl compile errors fixed for FreeBSD

+

+ Own Id: OTP-7817

+ + +

+ A bug in the inet driver for SCTP on Solaris showing for + e.g gen_sctp:abort/1 and gen_sctp:eof/1 has been + corrected. Patch suggestion by Simon Cornish.

+

+ Own Id: OTP-7866

+ + +
+ + +
Improvements and New Features + + +

+ The order of objects visited in select for ordered_set is + now documented.

+

+ Own Id: OTP-7339

+ + +

+ The runtime system with SMP support now uses multiple, + scheduler specific run queues, instead of one globally + shared run queue.

+

+ The lock protecting the shared run queue was heavily + contended, and the shared run queue also caused Erlang + processes to randomly migrate between schedulers with + negative cache effects as a result.

+

+ With the current scheduler specific run queue solution, + lock contention due to run queue protection has been + reduced, and Erlang processes are only migrated when + needed to balance the load between the schedulers. The + reduced amount of migration also reduce lock contention + on locks protecting the scheduler specific instances of + the erts internal memory allocators.

+

+ The scheduler specific run queues are also a necessity + for a lot of future planned NUMA (Non-Uniform Memory + Access) specific optimizations.

+

+ Own Id: OTP-7500

+ + +

Support for Unicode is implemented as described in + EEP10. Formatting and reading of unicode data both from + terminals and files is supported by the io and io_lib + modules. Files can be opened in modes with automatic + translation to and from different unicode formats. The + module 'unicode' contains functions for conversion + between external and internal unicode formats and the re + module has support for unicode data. There is also + language syntax for specifying string and character data + beyond the ISO-latin-1 range.

+

The interactive shell will support input and output of + unicode characters when the terminal and operating system + supports it.

+

Please see the EEP and the io/io_lib manual pages as + well as the stdlib users guide for details.

+

I/O-protocol incompatibilities:

+

The io_protocol between io_Server and client is + updated to handle protocol data in unicode formats. The + updated protocol is now documented. The specification + resides in the stdlib users manual, which is a + new part of the manual.

+

io module incompatibilities:

+

The io:put_chars, io:get_chars and io:get_line all + handle and return unicode data. In the case where + binaries can be provided (as to io:put_chars), they shall + be encoded in UTF-8. When binaries are returned (as by + io:get_line/get_chars when the io_server is set in + binary mode) the returned data is also + always encoded as UTF-8. The file module however + still returns byte-oriented data, why file:read can be + used instead of io:get_chars to read binary data in + ISO-latin-1.

+

io_lib module incompatibilities:

+

io_lib:format can, given new format directives (i.e + "~ts" and "~tc"), return lists containing integers larger + than 255.

+

+ *** POTENTIAL INCOMPATIBILITY ***

+

+ Own Id: OTP-7648 Aux Id: OTP-7580 OTP-7514 OTP-7494 + OTP-7443 OTP-7181 EEP10 EEP11

+ + +

+ The format of the string returned by + erlang:system_info(system_version) (as well as the + first message when Erlang is started) has changed. The + string now contains the both the OTP version number as + well as the erts version number.

+

+ Own Id: OTP-7649

+ + +

+ Message passing has been further optimized for parallel + execution. Serial message passing is slightly more + expensive than before, but parallel send to a common + receiver is much cheaper.

+

+ Own Id: OTP-7659

+ + +

+ Lock contention on the atom table lock when decoding + Erlang terms on the external format has been drastically + reduced.

+

+ Own Id: OTP-7660

+ + +

+ The undocumented, unsupported, and deprecated guard BIF + is_constant/1 has been removed.

+

+ *** INCOMPATIBILITY with R12B ***

+

+ Own Id: OTP-7673

+ + +

+ The Erlang process lock implementation has been improved + by Mat Hostetter at Tilera Corporation.

+

+ Own Id: OTP-7692

+ + +

+ A {nodedown, Node} message passed by the + net_kernel:monitor_nodes/X functionality is now + guaranteed to be sent after Node has been removed + from the result returned by erlang:nodes/Y.

+

+ Own Id: OTP-7725

+ + +

The short-circuit operators andalso and + orelse no longer guarantees that their second + argument is either true or false. As a + consequence, andalso/orelse are now + tail-recursive.

+

+ *** POTENTIAL INCOMPATIBILITY ***

+

+ Own Id: OTP-7748

+ + +

+ A new BIF, lists:keyfind/3, has been added. It + works like lists:keysearch/3 except that it does + not wrap the returned tuple in a value tuple in + case of success. (Thanks to James Hague for suggesting + this function.)

+

+ Own Id: OTP-7752

+ + +

+ Optimization for drivers by creating small binaries + direct on process heap.

+

+ Own Id: OTP-7762

+ + +

I bsl N could cause the Erlang virtual machine + to run of memory instead generating a system_limit + if N was absurdly huge. (Thanks to Daniel Hedlund.)

+

There would always be a garbage collection when + evaluating I bsl N or I bsr N if I + was a bignum.

+

If I is an integer and N a bignum, I + bsl N will now cause the correct system_limit + exception instead of bad_arith as in earlier + releases.

+

If I is an integer and N a bignum, I + bsr N will return either 0 or -1 depending on the + sign of I instead of causing a bad_arith + exception as in earlier releases.

+

+ Own Id: OTP-7764

+ + +

+ Scheduler threads can now be bound to logical processors + on newer Linux and Solaris systems. More systems will be + supported in the future.

+

+ In some cases performance has increased drastically when + binding schedulers. Schedulers are not bound by default, + though. This since it might cause a performance + degradation if multiple programs have bound to + processors, e.g. multiple Erlang runtime systems. For + more information see the documentation of + erlang:system_flag/2.

+

+ In order to bind scheduler threads the CPU topology need + to be known. On some newer Linux and Solaris systems the + runtime system automatically detects the CPU topology. If + the emulator isn't able to automatically detect the CPU + topology, the CPU topology can be defined. For more + information see the documentation of + erlang:system_flag/2.

+

+ Own Id: OTP-7777

+ + +

The compiler will refuse to a compile file where the + module name in the file differs from the output file + name.

+

When compiling using erlc, the current working + directory will no be included in the code path (unless + explicitly added using "-pa .").

+

+ *** POTENTIAL INCOMPATIBILITY ***

+

+ Own Id: OTP-7793

+ + +

+ The BIFs atom_to_binary/2, + binary_to_atom/2, and + binary_to_existing_atom/2 have been added.

+

+ Own Id: OTP-7804

+ + +

+ The amount of schedulers online can now be changed during + operation. The amount of schedulers online defaults to + the same amount as available logical processors. For more + information see the documentation of + erlang:system_flag/2 and erl.

+

+ Own Id: OTP-7811

+ + +

The deprecated functions erlang:fault/1, + erlang:fault/2, and file:rawopen/2 have + been removed.

+

+ *** POTENTIAL INCOMPATIBILITY ***

+

+ Own Id: OTP-7812

+ + +

+ Erts internal dynamically allocated process and port + specific data for rarely used data. This is used to + reduce memory usage of processes and ports that do not + use specific functionality. More functionality will be + moved to process and port specific data in future + releases.

+

+ Own Id: OTP-7818

+ + +

+ New packet type http_bin for gen_tcp sockets and + erlang:decode_packet. It works like http + except that strings are returned as binaries instead of + lists.

+

+ Own Id: OTP-7821

+ + +

+ The obsolete wd_keeper program for embedded Solaris + systems has been removed.

+

+ Own Id: OTP-7822

+ + +

+ Nodes belonging to different independent clusters can now + co-exist on the same host with the help of a new + environment variable setting ERL_EPMD_PORT.

+

+ Own Id: OTP-7826

+ + +

There are new functions erlang:min/2 and + erlang:max/2 to calculate the minimum and maximum + of two terms, respectively. Note that the functions are + not auto-imported, so they need to be imported explicitly + or the erlang prefix must be used when calling + them.

+

+ Own Id: OTP-7841

+ + +

The copyright notices have been updated.

+

+ Own Id: OTP-7851

+ + +

Enhanced build environment for cross compilation to + Tilera Tile architecture.

+

Support for native ethread atomics on Tilera + Tile64/TilePro (Thanks to Tilera Corporation).

+

+ Own Id: OTP-7852

+ + +

The escape sequences \x and \{ have been + assigned new interpretations (they used to return the + ASCII code for x and { respectively). One + or more octal characters inside curly brackets after a + leading backslash is from now on an alternative to the + existing syntax \NNN, but can also be used for + codes greater than 255. In a similar fashion, one or more + hexadecimal characters can be put inside curly brackets + after a leading \x. Furthermore, the escape + sequences \xH and \xHH, where N is a + hexadecimal character, can be used for codes less than + 256.

+

NOTE: These new escape sequences are still considered + experimental and may be changed in the R13B release.

+

+ *** POTENTIAL INCOMPATIBILITY ***

+

+ Own Id: OTP-7855

+ + +

+ The PCRE library's exported function names are now + prefixed with erts_ in the erlang emulator to avoid + clashes with dynamically loaded drivers.

+

+ Own Id: OTP-7861

+ + +

+ A runtime system with SMP support will now be built by + default on most platforms if a usable posix thread + library or native windows threads are found.

+

+ For more information see the top README file.

+

+ Own Id: OTP-7872

+ + +
+ +
+ + +
Erts 5.6.5.1 + +
Fixed Bugs and Malfunctions + + +

+ A corrected bug in ets for bag and + duplicate_bag. A delete/2 or + lookup_element/3 could miss objects in a fixed + table if one or more objects with the same key had + already been deleted.

+

+ Own Id: OTP-7665

+ + +

+ A bug fixed for TCP sockets with option + {packet,http}. An HTTP request with an absolute + URI was returned with a corrupt path string. This bug did + only exist in R12B-4 and R12B-5.

+

+ Own Id: OTP-7682 Aux Id: OTP-7647

+ + +

+ Calling gen_tcp:send() from several processes on + socket with option send_timeout could lead to much + longer timeout than specified. The solution is a new + socket option {send_timeout_close,true} that will + do automatic close on timeout. Subsequent calls to send + will then immediately fail due to the closed connection.

+

+ Own Id: OTP-7731 Aux Id: seq11161

+ + +

+ A process being garbage collected via the + garbage_collect/1 BIF or the + check_process_code/2 BIF didn't handle message + receive and resume correctly during the garbage collect. + When this occurred, the process returned to the state it + had before the garbage collect instead of entering the + new state.

+

+ Own Id: OTP-7738

+ + +
+ +
+ +
Erts 5.6.5 + +
Fixed Bugs and Malfunctions + + +

+ A bug in inet_drv concerning gen_tcp:connect has been + corrected. A connect towards a non-open port through open + firewalls could sometimes erroneously be successful. Any + subsequent operation would fail, though.

+

+ Own Id: OTP-6542

+ + +

+ Floating point arithmetics in drivers could cause a + runtime system crash and/or unexpected results on runtime + systems with floating point exceptions enabled. Floating + point exceptions are disabled unless explicitly enabled + or if hipe is enabled.

+

+ Own Id: OTP-7237

+ + +

+ A bug when many sockets got signalled simultaneously + causing the emulator to panic with the message + "Inconsistent, why isnt io reported?" is now corrected.

+

+ Own Id: OTP-7420

+ + +

+ Starting erl with option "-detached" now disconnects + correctly from terminal session on Unix.

+

+ Own Id: OTP-7461

+ + +

+ Mended gdb etp-commands for ETS access.

+

+ Own Id: OTP-7538

+ + +

+ erlang:decode_packet/3 allows white space between + HTTP header tag and colon according to RFC2616.

+

+ Own Id: OTP-7543

+ + +

+ An emulator compiled for SCTP now starts even if the + dynamic libraries are not present. The SCTP driver is + then of course not loaded.

+

+ Own Id: OTP-7551

+ + +

To build on Mac OS X, 10.3.0 or later is now required + because of fixes for two problems:

+

There would be a resource leak when erl_ddl + attempted to unload a driver. This problem has been + corrected by using dlopen() (which works on all + modern Unix-like platforms) instead of the Mac OS X + specific API calls.

+

Signal handling in the run-time system for HiPE has + been updated to work on later versions of Mac OS X than + 10.2.x. Therefore, --enable-hipe now works on Mac + OS X with Intel CPUs.

+

Thanks to Geoff Cant for the patches.

+

+ Own Id: OTP-7562

+ + +

Corrected some information about the protocol between + EPMD and Erlang nodes. (Thanks to Michael Regen.)

+

+ Own Id: OTP-7594

+ + +

+ When using + erlang:system_monitor(Pid,{long_gc,Time}), and the + GC time exceeded 1 second, it sometimes erroneously + showed up as about 4300 seconds. (This bug was corrected + in R9C, but re-introduced in R12B.) (Thanks to Chris + Newcombe.)

+

+ Own Id: OTP-7622 Aux Id: OTP-4903, seq8379

+ + +
+ + +
Improvements and New Features + + +

+ The driver entry of a dynamically loaded driver is now + copied when loaded which enables some internal + optimizations. Note that drivers that modify the driver + entry during execution will not work anymore. Such a + miss-use of the driver interface is however not + supported.

+

+ Own Id: OTP-6900

+ + +

+ The split function is now added to the re library. + Exceptions and errors from both run, replace and split + are made more consistent.

+

+ Own Id: OTP-7514 Aux Id: OTP-7494

+ + +

+ Fixed harmless compiler warnings when building the + emulator and minor build changes in order to avoid + unnecessary rebuilds.

+

+ Own Id: OTP-7530

+ + +

+ There is now experimental support for loading of code + from archive files. See the documentation of code, + init, erl_prim_loader and escript + for more info.

+

+ The error handling of escripts has been improved.

+

+ An escript may now set explicit arguments to the + emulator, such as -smp enabled.

+

+ An escript may now contain a precompiled beam + file.

+

+ An escript may now contain an archive file + containing one or more applications (experimental).

+

+ The internal module code_aux has been removed.

+

+ Own Id: OTP-7548 Aux Id: otp-6622

+ + +

+ The reallocation functionality part of the ERTS internal + memory allocators, now consider current block in + combination with surrounding free blocks as an + alternative location for a reallocation.

+

+ Own Id: OTP-7555

+ + +

There could remain false references from a process to + a module that has been called earlier, so that the + process would be killed if the module was reloaded. + (Thanks to Richard Carlsson.)

+

Also, the fix for this bug also made it possible to + make stack backtraces (as returned from + erlang:get_stacktrace/0 and other functions) more + correct in that the immediate caller is always included + in the stack backtrace (it could sometimes be + missing).

+

+ Own Id: OTP-7559

+ + +

+ Improved locking in IO-handling for better smp + performance.

+

+ Own Id: OTP-7560

+ + +

+ Improved BIF rescheduling functionality.

+

+ Own Id: OTP-7587

+ + +

+ Loading a module compiled with Erlang/OTP R9C and calling + module_info/0 in the module would crash the + emulator. The emulator now refuses to load any module + compiled with R9C or earlier. (Note: only trivial modules + compiled with R10B or earlier could be loaded anyway.) + (Thanks to Martin Kjellin.)

+

+ Own Id: OTP-7590

+ + +
+ +
+ +
Erts 5.6.4.2 + +
Fixed Bugs and Malfunctions + + +

+ A process calling one of the following BIFs could under + very rare conditions deadlock in the runtime system with + SMP support: check_process_code/2, + garbage_collect/1, process_info/[1,2], + system_flag/2, and + erlang:suspend_process/[1,2].

+

+ Own Id: OTP-7582

+ + +

+ A couple of statistics variables were not managed in a + thread safe manner in the runtime system with SMP + support.

+

+ Own Id: OTP-7583

+ + +

+ An extremely rare race condition when terminating a + process could potentially cause a runtime system crash.

+

+ Own Id: OTP-7584

+ + +

+ Under certain conditions and when using run_erl/to_erl, + the terminal Erlang driver (ttsl_drv) could crash the + emulator by doing a division by zero due to incorrect + handling of terminals reporting a zero width. For + terminals reporting zero width, the driver now fallbacks + to a default width of 80 and a default height of 24 + (vt100), as a fallback behaviour. This fixes the crashes + and also makes output on "dumb" terminals much more + readable.

+

+ Own Id: OTP-7592 Aux Id: seq11073

+ + +
+ +
+ +
Erts 5.6.4.1 + +
Improvements and New Features + + +

+ A new erts_alloc parameter + +M<S>rmbcmt (relative multiblock carrier + move threshold) has been added. It determines when to + force a moving realloc in a multiblock carrier when a + block is shrunk. For more information see the + erts_alloc(3) documentation.

+

+ Own Id: OTP-7540

+ + +

The new option +d can be given to erl to + suppress the crash dump generation if an internal error + is detected. As a result, a more useful core dump is + produced.

+

+ Own Id: OTP-7578 Aux Id: seq11052

+ + +
+ +
+ +
Erts 5.6.4 + +
Fixed Bugs and Malfunctions + + +

+ Double backslashes in format string passed to the erts + internal printf implementation produced erroneous + results. No such format strings were passed to the erts + internal printf implementation, i.e., the bug was + therefore completely harmless. (Thanks to Perry Smith.)

+

+ Own Id: OTP-7408

+ + +

+ Large files are now handled on Windows, where the + filesystem supports it.

+

+ Own Id: OTP-7410

+ + +

+ Bug fixed for {packet,http} when space follows + http headers.

+

+ Own Id: OTP-7458

+ + +

+ The trace option running could cause an emulator + crash if the current function couldn't be determined.

+

+ Own Id: OTP-7484

+ + +

+ Using 16#ffffFFFF as a timeout value in receive...after + would often cause a timeout almost at once due to an + 32-bit integer overflow. (Thanks to Serge Aleynikov and + Matthias Lang.)

+

+ Own Id: OTP-7493

+ + +

+ For the process that an escript runs in, the + trap_exit process flag is now false instead + of true (as in previous releases). Scripts that + depend on the previous (counter-intuitive) behaviour + might not work. (Thanks to Bengt Kleberg.)

+

+ *** POTENTIAL INCOMPATIBILITY ***

+

+ Own Id: OTP-7517

+ + +

+ A bug in the string:to_integer/1 builtin made the + emulator unstable. This is now corrected. (Thanks to Lev + Walkin.)

+

+ Own Id: OTP-7526

+ + +
+ + +
Improvements and New Features + + +

Performance for ETS intensive applications should now + be better in the SMP emulator. Also, ETS table + identifiers (as returned by ets:new/2) are now + spread out in wider range than before (using 28 bits in a + 32-bit emulator) to make sure that the table identifier + for a deleted table will not be quickly re-used.

+

NOTE: Table identifiers can now be negative integers. + Programs that (incorrectly) assume that table identifiers + can only be positive integers might stop to work. (The + type of a table identifier is intentionally not + documented, and may change in a future release.)

+

+ Own Id: OTP-7348

+ + +

+ New BIF erlang:decode_packet/3 that extracts a + protocol packet from a binary. Similar to the socket + option {packet, Type}. Also documented the socket + packet type http and made it official. + NOTE: The tuple format for http packets + sent from an active socket has been changed in an + incompatible way.

+

+ *** POTENTIAL INCOMPATIBILITY ***

+

+ Own Id: OTP-7404

+ + +

+ The source code for the documentation for some + applications (erts, kernel, stdlib, and several others) + are now included in the source tar ball. There is + currently no Makefile support for building HTML files + from the source (such support will be included in a + future release).

+

+ Own Id: OTP-7406

+ + +

+ A lot of frequently accessed memory counters (erts + internal) have been removed. This since they hurt + performance on the runtime system with SMP support. As a + result erlang:memory/[0,1] will only deliver a + result if all erts_alloc(3) allocators are enabled + (default). The result delivered when all + erts_alloc(3) allocators are enabled are both more + accurate and less accurate than before. More memory than + before are included in the result, but the different + parts that are summed are not gathered atomically. A call + to erlang:memory/[0,1] is much cheaper for the + system than before. This since the information isn't + gathered atomically anymore which was very expensive.

+

+ *** POTENTIAL INCOMPATIBILITY ***

+

+ Own Id: OTP-7468

+ + +

+ Pre-allocators used for, for example, timers, and + messages have been rewritten to be scheduler specific. + That is, different schedulers will now allocate from + different pools which reduces lock contention.

+

+ Own Id: OTP-7470

+ + +

+ On Mac OS X, file:sync/1 now guarantees that all + filesystem buffers are written to the disk by using the + fcntl() with F_FULLFSYNC option. Previously, file:sync/1 + called fsync(), which only guaranteed that the data had + been transferred to the disk drive. (Thanks to Jan + Lehnardt.)

+

+ Own Id: OTP-7471

+ + +

+ Termination of a process that takes a long time can now + be preempted, i.e., the terminating process will be + rescheduled for later continuation of termination so that + other processes can execute. Termination of a process + that owns many and/or large ets tables typically takes a + long time.

+

+ Own Id: OTP-7477

+ + +

+ A new trace option exiting has been added. The + exiting trace is similar to the running + trace, but for exiting processes. For more information + see the erlang(3) documentation.

+

+ The erlang:trace/3 bif now doesn't block other + scheduler threads if only one tracee is specified in the + call to erlang:trace/3.

+

+ Own Id: OTP-7481

+ + +

+ The re module is extended with repetitive matches (global + option) and replacement function.

+

+ Own Id: OTP-7494 Aux Id: OTP-7181

+ + +

+ In the section about binary construction, the reference + manual now mentions what happens when an integer value + does not fit into an integer segment of size N (namely, + that the N least significant bits will be put into into + the binary and that the most significant bits will be + silently discarded). (Thanks to Edwin Fine.)

+

+ Own Id: OTP-7506

+ + +

+ Setting the {active,once} for a socket (using + inets:setopts/2) is now specially optimized (because the + {active,once} option is typically used much more + frequently than other options).

+

+ Own Id: OTP-7520

+ + +
+ + +
Known Bugs and Problems + + +

+ Floating point arithmetics in drivers can cause a runtime + system crash and/or unexpected results on runtime systems + with floating point exceptions enabled. Floating point + exceptions are disabled unless explicitly enabled or if + hipe is enabled.

+

+ Own Id: OTP-7237

+ + +
+ +
+ +
Erts 5.6.3.3 + +
Fixed Bugs and Malfunctions + + +

+ Binary construction with an integer field of size 0 at + the end of the constructed binary (and the size given in + a variable), would cause a write of one byte outside the + memory reserved for the binary, which in turn could cause + an emulator crash.

+

+ Own Id: OTP-7422

+ + +

+ A race condition in the dynamic driver implementation + could cause an emulator crash. (Thanks to Paul Fisher)

+

+ Own Id: OTP-7464

+ + +

+ Calls to erlang:system_info(allocated_areas) could + cause the runtime system with SMP support to crash.

+

+ Own Id: OTP-7474

+ + +

+ The env option to open_port() could cause + the runtime system with SMP support to crash.

+

+ Own Id: OTP-7475

+ + +
+ + +
Improvements and New Features + + +

+ Operations that needed to block other threads in the + runtime system with SMP support unnecessarily waited for + async threads to block. Most important the + erlang:memory/[0,1] bif, code loading, and the + erlang:trace/3 bif.

+

+ Own Id: OTP-7480

+ + +
+ +
+ +
Erts 5.6.3.2 + +
Fixed Bugs and Malfunctions + + +

+ Calls to erlang:memory/[0,1] could cause the + runtime system with SMP support to crash.

+

+ Own Id: OTP-7415

+ + +
+ +
+ +
Erts 5.6.3.1 + +
Fixed Bugs and Malfunctions + + +

+ Doing local call trace on bit syntax matching code that + has been optimized with delayed sub-binary creation could + crash the emulator.

+

+ Own Id: OTP-7399 Aux Id: seq10978

+ + +
+ +
+ +
Erts 5.6.3 + +
Fixed Bugs and Malfunctions + + +

+ Only one to_erl process at a time is allowed to connect + to the same run_erl pipe. Prevents buggy behaviour when + IO from several to_erl's get interleaved.

+

+ Own Id: OTP-5107

+ + +

+ IPv6 name resolving has now been fixed to use + getaddrinfo() patch (thoroughly reworked) courtesy of Love + Hörnquist-Åstrand submitted by Fredrik Thulin. It also + can use gethostname2() patch (also reworked) courtesy of + Mikael Magnusson for debian submitted by Sergei Golovan.

+

+ Own Id: OTP-5382

+ + +

+ Improved error handling in run_erl

+

+ Own Id: OTP-7252

+ + +

A permanent fix for the deadlock issue temporarily + fixed by OTP-7260.

OTP-7260 + The runtime system with SMP support could under rare + circumstances deadlock when a distribution channel was + taken down while multiple simultaneous operations were + performed on it. +

+ Own Id: OTP-7267 Aux Id: OTP-7260

+ + +

+ ./configure has been improved to find 64-bit OpenSSL + libraries.

+

+ Own Id: OTP-7270

+ + +

+ A terminating process could under very rare circumstances + trigger a bug which could crash the runtime system with + SMP support.

+

+ Own Id: OTP-7272

+ + +

+ SCTP_ADDR_CONFIRMED events are now handled by gen_sctp.

+

+ Own Id: OTP-7276

+ + +

+ binary_to_term/1 would crash the emulator if the binary + data contained an external fun with non-atom module + and/or function. Corrected to generate a badarg + exception.

+

+ Own Id: OTP-7281

+ + +

+ On Mac OS 10.5 (Leopard), sending to socket which the + other end closes could cause the emulator to consume 100% + CPU time. (Thanks to Matthias Radestock.)

+

+ Own Id: OTP-7289

+ + +

+ The vanilla driver used on Windows could crash the + emulator and sometimes produced corrupt files. The + vanilla driver is the driver that is used when one only + pass a filename as first argument to open_port/2. + NOTE: This use of open_port/2 is + obsolete, and the documentation of this use has + previously been removed. The functionality is only + present for backward compatibility reasons and + will eventually be removed.

+

+ Own Id: OTP-7301

+ + +

+ Faulty matching in binaries larger than 512Mb on 64bit + machines fixed.(On 32bit, the size limit for binaries is + still 512Mb). Thanks to Edwin Fine and Per Gustafsson for + finding fault and fix.

+

+ Own Id: OTP-7309

+ + +

+ crypto:start() on Windows caused emulator to hang on + error popup window if openssl DLL was not found. Windows + error popups now suppressed.

+

+ Own Id: OTP-7325

+ + +

+ Configuration option without-termcap can be used to + disable the use of termcap libraries for terminal cursor + control in the shell.

+

+ Own Id: OTP-7338

+ + +

+ to_erl reports its terminal window size to run_erl in + order to get output formatted accordingly

+

+ Own Id: OTP-7342

+ + +

+ On Solaris, the compressed option for file + operations did not work if the file descriptor happened + to be greater than 255 (a problem with fopen() and + friends in Solaris itself).

+

+ Own Id: OTP-7343 Aux Id: seq10949

+ + +

+ A race condition in the runtime system with SMP support + causing an erroneous removal of a newly created ets table + has been fixed.

+

+ The race occurred when a process removed a table during + termination simultaneously as another process removed the + same table via ets:delete/1 and a third process + created a table that accidentaly got the same internal + table index as the table being removed.

+

+ Own Id: OTP-7349

+ + +

+ zlib:inflate failed when the size of the inflated + data was an exact multiple of the internal buffer size + (4000 bytes by default).

+

+ Own Id: OTP-7359

+ + +

+ If the total number of allowed atoms is exceeded, there + will now be a controlled termination of the emulator with + a crash dump file. The emulator used to simply crash. + (Thanks Howard Yeh and Thomas Lindgren.)

+

+ Own Id: OTP-7372

+ + +

+ The break handler in werl on Windows could cause the + emulator to hang or crash, that is now corrected.

+

+ Own Id: OTP-7394 Aux Id: seq10969

+ + +

+ The configure script now tests for an serious + optimization bug in gcc-4.3.0. If the bug is present, the + configure script will abort (if this happens, the only + way to build Erlang/OTP is to change to another version + of gcc). (Thanks to Mikael Pettersson.)

+

+ Own Id: OTP-7397

+ + +
+ + +
Improvements and New Features + + +

+ On Unix, the emulator now notices when the width of the + terminal has changed. (Thanks to Matthew Dempsky and + Patrick Mahoney.)

+

+ Own Id: OTP-7290

+ + +

+ There is a new function init:stop/1 which can be + used to shutdown the system cleanly AND generate a + non-zero exit status or crash dump. (Thanks to Magnus + Froberg.)

+

+ Own Id: OTP-7308

+ + +

+ process_info(Pid, garbage_collection) now returns more + information

+

+ Own Id: OTP-7311

+ + +

+ The hide option for open_port/2 is now + documented. (Thanks to Richard Carlsson.)

+

+ Own Id: OTP-7358

+ + +
+ + +
Known Bugs and Problems + + +

+ Floating point arithmetics in drivers can cause a runtime + system crash on runtime systems with floating point + exceptions enabled. Floating point exceptions are + disabled unless explicitly enabled or if hipe is enabled.

+

+ Own Id: OTP-7237

+ + +
+ +
+ + +
Erts 5.6.2 + +
Fixed Bugs and Malfunctions + + +

+ The maximum length of an atom of 255 characters is now + strictly enforced. binary_to_term/1 will now fail + with a badarg if an encoded term contains an atom longer + than 255 characters. Atoms created by drivers will now be + truncated to 255 characters if necessary. (Thanks to + Matthew Dempsky.)

+

+ Own Id: OTP-7147

+ + +

+ A bug in "bignum handling" on some 64bit architectures + could cause rem and div operations on large numbers to + hang indefinitely. Rem operations involving the smallest + negative number representable in 28 bits or 60 bits could + also cause access violation and emulator crash. Both + errors are corrected.

+

+ Own Id: OTP-7177

+ + +

+ When doing the initial garbage collection after waking a + hibernated process, a fullsweep garbage collection was + unnecessarily triggered.

+

+ Own Id: OTP-7212

+ + +

The beta testing module gen_sctp now supports + active mode as stated in the documentation. Active mode + is still rather untested, and there are some issues about + what should be the right semantics for + gen_sctp:connect/5. In particular: should it be + blocking or non-blocking or choosable. There is a high + probability it will change semantics in a (near) future + patch.

Try it, give comments and send in bug + reports!

+

+ Own Id: OTP-7225

+ + +

+ Invalid arguments to ets:update_counter/3 were not + handled correctly. A tuple position (Pos) less + than 1 caused the element directly following the key to + be updated (as if no position at all had been specified). + All invalid values for Pos will now fail with + badarg.

+

+ Own Id: OTP-7226

+ + +

+ The runtime system with SMP support could under rare + circumstances deadlock when a distribution channel was + taken down while multiple simultaneous operations were + performed on it.

+

+ Own Id: OTP-7260

+ + +
+ + +
Improvements and New Features + + +

+ More checksum/hash algorithms from the zlib library are + now available as built in functions (like md5 hashes has + been for a long time).

+

+ Own Id: OTP-7128

+ + +

+ Minor improvements in the garbage collector.

+

+ Own Id: OTP-7139 Aux Id: OTP-7132

+ + +

+ The switch "-detached" to the windows werl program now + can create an erlang virtual machine without any main + window and without a temporary console showing.

+

+ Own Id: OTP-7142

+ + +

erlang:system_info/1 now accepts the + logical_processors, and debug_compiled + arguments. For more info see the, erlang(3) + documentation.

The scale factor returned by + test_server:timetrap_scale_factor/0 is now also + effected if the emulator uses a larger amount of + scheduler threads than the amount of logical processors + on the system.

+

+ Own Id: OTP-7175

+ + +

+ A new BIF ets:update_element/3. To update individual + elements within an ets-tuple, without having to read, + update and write back the entire tuple.

+

+ Own Id: OTP-7200

+ + +

+ A process executing the processes/0 BIF can now be + preempted by other processes during its execution. This + in order to disturb the rest of the system as little as + possible. The returned result is, of course, still a + consistent snapshot of existing processes at a time + during the call to processes/0.

+

+ The documentation of the processes/0 BIF and the + is_process_alive/1 BIF have been updated in order + to clarify the difference between an existing process and + a process that is alive.

+

+ Own Id: OTP-7213

+ + +
+ +
+ + +
Erts 5.6.1.1 + +
Fixed Bugs and Malfunctions + + +

+ Not enough parameters were passed when sending an error + report in erl_check_io.c (Thanks to Matthew Dempsky).

+

+ Own Id: OTP-7176

+ + +

+ In rare circumstances, complex binary matching code could + cause the emulator to crash or not match when it should. + (Thanks to Rory Byrne.)

+

+ Own Id: OTP-7198

+ + +
+ + +
Improvements and New Features + + +

The {allocator_sizes, Alloc} and + alloc_util_allocators arguments are now accepted + by erlang:system_info/1. For more information see + the erlang(3) documentation.

+

+ Own Id: OTP-7167

+ + +

+ The finishing reallocation of the heap block when + hibernating a process is now always moving the heap block + since it drastically reduces memory fragmentation when + hibernating large amounts of processes.

+

+ Own Id: OTP-7187

+ + +
+ +
+ +
Erts 5.6.1 + +
Fixed Bugs and Malfunctions + + +

+ The SMP emulator on sparc64 erroneously used the sparc32 + atomic and the sparc32 spinlock implementations which + caused it to crash.

+

+ Own Id: OTP-7006

+ + +

+ Call tracing the new guard BIFs byte_size, + bit_size, or tuple_size and the loading a + module that uses one of those functions, could cause the + emulator to terminate.

+

+ Own Id: OTP-7008

+ + +

+ configuring --enable-darwin-universal or + --enable-darwin-64bit on MacOSX could result in a non + optimized emulator. Top level configure script now + corrected.

+

+ Own Id: OTP-7014

+ + +

+ configuring --with-gd did not produce correct include + flags for percept.

+

+ Own Id: OTP-7015

+ + +

+ Environment variables weren't handled in thread safe + manner in the runtime system with SMP support on Windows.

+

+ erl_drv_putenv(), and erl_drv_getenv() has + been introduced for use in drivers. Do not use + putenv(), or getenv() directly in drivers. For more + information see the erl_driver documentation.

+

+ Own Id: OTP-7035

+ + +

+ HIPE: Corrected the choice of interface to the send/3 and + setnode/3 BIFs for native-compiled code. Using the + incorrect interface could, in unusual circumstances, lead + to random runtime errors.

+

+ Own Id: OTP-7067

+ + +

+ Garbage collections could become extremely slow when + there were many keys in the process dictionary. (Thanks + to Fredrik Svahn.)

+

+ Own Id: OTP-7068

+ + +

+ The duplicate documentation directory in the windows + installation is removed.

+

+ Own Id: OTP-7070

+ + +

Documentation bugfixes and clarifications.

(Thanks + to Joern (opendev@gmail.com), Matthias Lang, and Richard + Carlsson.) +

+ Own Id: OTP-7079

+ + +

+ The runtime system with SMP support not using + the native atomic integer implementation part of OTP + could deadlock when run on a system with more than one + logical processor. That is, only the runtime system with + SMP support on other hardware platforms than + x86, x86_64, sparc32, and powerpc32 were effected by this + bug.

+

+ Own Id: OTP-7080

+ + +

+ The break handling code (run when Ctrl-C is hit) could + could potentially deadlock the runtime system with SMP + support.

+

+ Own Id: OTP-7104

+ + +

+ The sctp driver has been updated to work against newer + lksctp packages e.g 1.0.7 that uses the API spelling + change adaption -> adaptation. Older lksctp (1.0.6) still + work. The erlang API in gen_sctp.erl and inet_sctp.hrl + now spells 'adaptation' regardless of the underlying C + API.

+

+ *** POTENTIAL INCOMPATIBILITY ***

+

+ Own Id: OTP-7120

+ + +

A bug in erlang:phash2/1 on 64-bit platforms + has been fixed. (Thanks to Scott Lystig Fritchie.)

+

+ Own Id: OTP-7127

+ + +

+ The emulator could under rare circumstances crash while + garbage collecting.

+

+ Own Id: OTP-7132

+ + +
+ + +
Improvements and New Features + + +

The documentation has been updated so as to reflect + the last updates of the Erlang shell as well as the minor + modifications of the control sequence p of the + io_lib module.

Superfluous empty lines have + been removed from code examples and from Erlang shell + examples.

+

+ Own Id: OTP-6944 Aux Id: OTP-6554, OTP-6911

+ + +

+ Bit syntax construction with a small integer in a + non-byte aligned field wider than the CPU's word size + could cause garbage bits in the beginning of the field.

+

+ Own Id: OTP-7085

+ + +

+ All Windows versions older than Windows 2000 are now + not supported by the Erlang runtime system. This + since there was a need for usage of features introduced + in Windows 2000.

+

+ Own Id: OTP-7086

+ + +

Memory management improvements especially for the + runtime system with SMP support:

The + runtime system with SMP support can now use multiple, + thread specific instances of most memory allocators. This + improves performance since it reduces lock contention in + the memory allocators. It may however increase memory + usage for some applications. The runtime system with SMP + support will by default enable this feature on most + allocators. The amount of instances used can be + configured. driver_alloc(), + driver_realloc(), and driver_free() now use + their own erts specific memory allocator instead of the + default malloc() implementation on the system. + The default configuration of some + allocators have been changed to fit applications that use + much memory better. Some new + erts_alloc configuration parameters have been + added. erts_alloc_config has been + modified to be able to create configurations suitable for + multiple instances of allocators. The + returned value from erlang:system_info({allocator, + Alloc}) has been changed. This since an allocator may + now run in multiple instances.

If you + for some reason want the memory allocators to be + configured as before, you can pass the +Mea r11b + command-line argument to erl.

For more + information see the erts_alloc(3), the + erts_alloc_config(3), and the erlang(3) + documentation.

+

+ *** POTENTIAL INCOMPATIBILITY ***

+

+ Own Id: OTP-7100

+ + +

+ On Unix, denormalized floating point numbers could not be + created using list_to_float/1 or + binary_to_term/1. (Thanks to Matthew Dempsky.)

+

+ Own Id: OTP-7122

+ + +

+ Native atomic integers and spin-locks are now also + available for the runtime system with SMP support on + sparc64.

+

+ Own Id: OTP-7130

+ + +

+ FP exceptions support for sparc64 userspace on Linux has + been added. Note that FP exception support is now turned + off by default, so to actually enable it you need to do + './configure --enable-fp-exceptions'.

+

+ Own Id: OTP-7131

+ + +
+ +
+ +
Erts 5.6 + +
Fixed Bugs and Malfunctions + + +

+ A bug for raw files when reading 0 bytes returning 'eof' + instead of empty data has been corrected.

+

+ Own Id: OTP-6291 Aux Id: OTP-6967

+ + +

+ All exported functions in gzio.c have now been renamed to + avoid conflict with drivers that are indirectly linked + with an external zlib library.

+

+ Own Id: OTP-6816 Aux Id: OTP-6591

+ + +

+ On the 64-bit Erlang emulator, bit syntax construction + with integers containing more than 60 bits ("big + numbers") into fields with more than 60 bits could + produce incorrect results.

+

+ Own Id: OTP-6833

+ + +

+ When the runtime system failed to allocate memory for + binaries, it could dead lock while writing the + erl_crash.dump.

+

+ Own Id: OTP-6848

+ + +

+ The runtime system with SMP support could deadlock if a + process called the erlang:suspend_process(Pid) BIF + or the erlang:garbage_collect(Pid) BIF while the + process identified by Pid was currently running + and the process calling the BIFs was terminated during + the call to the BIFs.

+

+ Processes suspending each other via the + erlang:suspend_process/1 BIF or garbage collecting + each other via the erlang:garbage_collect/1 BIF + could deadlock each other when the runtime system with + SMP support was used.

+

+ Own Id: OTP-6920

+ + +

+ dbg could leave traced processes in a suspended + state if the tracer process was killed with exit reason + kill.

+

+ erlang:suspend_process/2 has been introduced which + accepts an option list as second argument. For more + information see the erlang(3) documentation.

+

+ Processes suspended via + erlang:suspend_process/[1,2] will now be + automatically resumed if the process that called + erlang:suspend_process/[1,2] terminates.

+

+ Processes could previously be suspended by one process + and resumed by another unless someone was tracing the + suspendee. This is not possible anymore. The + process resuming a process has to be the one + that suspended it.

+

+ *** POTENTIAL INCOMPATIBILITY ***

+

+ Own Id: OTP-6946

+ + +

file:write_file/3, file:write/2 and file:read/2 could + crash (contrary to documentation) for odd enough file + system problems, e.g write to full file system. This bug + has now been corrected.

In this process the file + module has been rewritten to produce better error codes. + Posix error codes now originate from the OS file system + calls or are generated only for very similar causes (for + example 'enomem' is generated if a memory allocation + fails, and 'einval' is generated if the file handle in + Erlang is a file handle but currently invalid).

+

More Erlang-ish error codes are now generated. For + example {error,badarg} is now returned from + file:close/1 if the argument is not of a file + handle type. See file(3).

The possibility to write + a single byte using file:write/2 instead of a list + or binary of one byte, contradictory to the + documentation, has been removed.

+

+ *** POTENTIAL INCOMPATIBILITY ***

+

+ Own Id: OTP-6967 Aux Id: OTP-6597 OTP-6291

+ + +

+ Monitor messages produced by the system monitor + functionality, and garbage collect trace messages could + contain erroneous heap and/or stack sizes when the actual + heaps and/or stacks were huge.

+

+ As of erts version 5.6 the large_heap option to + erlang:system_monitor/[1,2] has been modified. The + monitor message is sent if the sum of the sizes of all + memory blocks allocated for all heap generations is equal + to or larger than the specified size. Previously the + monitor message was sent if the memory block allocated + for the youngest generation was equal to or larger than + the specified size.

+

+ *** POTENTIAL INCOMPATIBILITY ***

+

+ Own Id: OTP-6974 Aux Id: seq10796

+ + +

+ inet:getopts/2 returned random values on Windows + Vista.

+

+ Own Id: OTP-7003

+ + +
+ + +
Improvements and New Features + + +

+ The emulator internal process lock implementation has + been rewritten and optimized. A slight risk of starvation + existed in the previous implementation. This risk has + also been eliminated in the new implementation.

+

+ Own Id: OTP-6500

+ + +

+ Bitstrings (bit-level) binaries and binary comprehensions + are now part of the language. See the Reference Manual.

+

+ Own Id: OTP-6558

+ + +

+ The windows version of erlang now has SMP support. The + SMP emulator is run by default on machines which shows + more than one virtual or physical processor.

+

+ Own Id: OTP-6560 Aux Id: OTP-6925

+ + +

+ The details of the compressed term format has been + documented in erl_ext_dist.txt. (Thanks to Daniel + Goertzen.)

+

+ Own Id: OTP-6755

+ + +

+ The runtime system with SMP support is now started by + default if more than one logical processor are detected. + For more information, see the erl(3) + documentation.

+

+ Own Id: OTP-6756

+ + +

+ The external format for Erlang terms and the distribution + protocol are now documented in ERTS User's Guide.

+

+ Own Id: OTP-6779

+ + +

+ New BIF's erlang:system_profile/1 and + erlang:system_profile/2. These BIF's controls concurrency + profiling options for processes, ports and schedulers.

+

+ Own Id: OTP-6783 Aux Id: OTP-6285

+ + +

+ The ErlDrvTermData term types used by + driver_output_term() and driver_send_term() + have been extended with the term types + ERL_DRV_BUF2BINARY, ERL_DRV_EXT2TERM, and + ERL_DRV_UINT. ERL_DRV_BUF2BINARY is used + for passing and creating a binary, + ERL_DRV_EXT2TERM is used for passing terms encoded + with the external term format, and ERL_DRV_UINT is + used for passing unsigned integers.

+

+ Also the data types ErlDrvUInt and + ErlDrvSInt have been added which makes it more + obvious how arguments to term types are interpreted with + regards to width and signedness.

+

+ The incorrect data types ErlDriverTerm, + ErlDriverBinary, and ErlDriverPort in the + erl_driver(3) documentation have been replaced + with the correct data types ErlDrvTermData, + ErlDrvBinary, and ErlDrvPort.

+

+ For more information see the erl_driver(3) + documentation.

+

+ Own Id: OTP-6823

+ + +

+ Miscellaneous improvements of the erts internal thread + library.

+

+ It now support optimized atomic operations and spin-locks + on windows.

+

+ Fall-backs based on mutexes and/or spin-locks for missing + optimized atomic operations, spin-locks, or rwlocks has + been implemented. This makes it possible to compile the + runtime system with SMP support on a lot more platforms.

+

+ Default stack size on OpenBSD has been increased to 256 + kilo-words.

+

+ Own Id: OTP-6831 Aux Id: OTP-6560

+ + +

Many bit syntax operations, both construction and + matching, are faster. For further information, see the + Efficiency Guide.

+

+ Own Id: OTP-6838

+ + +

Literal lists, tuples, and binaries are no longer + constructed at run-time as they used to be, but are + stored in a per-module constant pool. Literals that are + used more than once are stored only once.

+

This is not a change to the language, only in the + details of its implementation. Therefore, the + implications of this change is described in the + Efficiency Guide.

+

Example 1: In the expression element(BitNum-1, + {1,2,4,8,16,32,64,128}), the tuple used to be + constructed every time the expression was executed, which + could be detrimental to performance in two ways if the + expression was executed in a loop: the time to build the + tuple itself and the time spent in garbage collections + because the heap filled up with garbage faster.

+

Example 2: Literal strings, such as "abc", used + to be stored in the compiled code compactly as a byte + string and expanded to a list at run-time. Now all + strings will be stored expanded to lists (such as + [$a,$b,$c]) in the constant pool. That means that + the string will be faster to use at run-time, but that it + will require more space even when not used. If space is + an issue, you might want to use binary literals (that is, + <<"abc">>) instead of string literals for + infrequently used long strings (such as error + messages).

+

+ Own Id: OTP-6850

+ + +

The Erlang driver API has been extended with a + portable POSIX thread like API for multi-threading. The + Erlang driver thread API provides:

+ Threads Mutexes Condition + variables Read/Write locks + Thread specific data

For more + information see the erl_driver(3) + documentation.

+

+ Own Id: OTP-6857

+ + +

+ Recursive calls now usually consume less stack than in + R11B. See the Efficiency Guide.

+

+ Own Id: OTP-6862 Aux Id: seq10746

+ + +

+ The deprecated BIFs erlang:old_binary_to_term/1 + and erlang:info/1 have been removed.

+

+ *** POTENTIAL INCOMPATIBILITY ***

+

+ Own Id: OTP-6876

+ + +

+ Calls to driver call-backs triggered by external events + are now scheduled and interleaved with execution of + Erlang processes also on the runtime system without SMP + support.

+

+ Own Id: OTP-6878

+ + +

+ Faster arithmetic of integers of more than 27 bits signed + (or 60 bits signed on an 64-bit CPU), and also faster + integer multiplication. (Thanks to Tony Rogvall.)

+

+ Own Id: OTP-6891

+ + +

Significant improvements of the process_info + BIFs:

process_info/2 can now be + called with a list of items as second argument in order + to atomically retrieve information about multiple items. + process_info/[1,2] has been + optimized in the runtime system with SMP support. The + whole scheduler could previously be blocked for a + significant period of time in process_info/[1,2] + waiting for a lock on the process being inspected. The + Erlang process calling process_info/[1,2] can + still be blocked for a significant period of time waiting + for the lock, but the scheduler will now be able to run + other processes while the process calling + process_info/[1,2] waits for the lock. + process_info/2 now accept a few more items + than before. The documentation of + process_info/[1,2] has been improved. +

For more information see the erlang(3) + documentation.

+

+ Own Id: OTP-6899

+ + +

+ open_port({}, []) could crash the emulator. + (Thanks to Matthew Dempsky.)

+

+ Own Id: OTP-6901

+ + +

Two new guard BIFs have been introduced as a + recommended replacement for size/1. (The + size/1 BIF will be removed no earlier than in + R14B.) The BIFs are tuple_size/1 to calculate the + size of a tuple and byte_size/1 to calculate the + number of bytes needed for the contents of the binary or + bitstring (rounded up to the nearest number of bytes if + necessary).

+

There is also a new bit_size/1 BIF that returns + the exact number of bits that a binary or bitstring + contains.

+

+ Own Id: OTP-6902

+ + +

The ets:fixtable/2 function, which has been + deprecated for several releases, has been removed.

+

The ets:info/1 function has been reimplemented + as a BIF, which guarantees that information returned is + consistent.

+

The ets:info/2 function now fails with reason + badarg if the second argument is invalid. + (Dialyzer can be used to find buggy code where the second + argument is misspelled.)

+

+ *** POTENTIAL INCOMPATIBILITY ***

+

+ Own Id: OTP-6906

+ + +

+ As the linux kernel may generate a minor fault when + tracing with CPU timestamps, and there exists no patch to + the Linux kernel that fixes the problem, cpu timestamps + are disabled on Linux for now.

+

+ *** POTENTIAL INCOMPATIBILITY ***

+

+ Own Id: OTP-6922

+ + +

The functions io:columns/0, io:columns/1, io:rows/0 + and io:rows/1 are added to allow the user to get + information about the terminal geometry. The shell takes + some advantage of this when formatting output. For + regular files and other io-devices where height and width + are not applicable, the functions return + {error,enotsup}.

+

Potential incompatibility: If one has written a custom + io-handler, the handler has to either return an error or + take care of io-requests regarding terminal height and + width. Usually that is no problem as io-handlers, as a + rule of thumb, should give an error reply when receiving + unknown io-requests, instead of crashing.

+

+ *** POTENTIAL INCOMPATIBILITY ***

+

+ Own Id: OTP-6933

+ + +

+ driver_caller() can now also be used from the + start callback of a driver.

+

+ Own Id: OTP-6951

+ + +

+ The emulator can now be compiled for 64bit intel, as well + as a 32bit universal binary on darwin/MacOSX 10.4 and + 10.5.

+

+ Own Id: OTP-6961

+ + +

+ If open_port fails because all available ports are + already in use, it will now throw a system_limit + exception instead of an enfile exception. + (enfile might still be thrown if the operating + system would return ENFILE.)

+

+ Own Id: OTP-6968

+ + +

+ The spawn_monitor/1 and spawn_monitor/3 BIFs + are now auto-imported (i.e. they no longer need an + erlang: prefix).

+

+ Own Id: OTP-6975

+ + +

+ On Windows, the werl window now handles resize, so that + the whole window can be utilized. Text selection is also + updated to be line oriented instead of rectangle oriented + as in earlier versions.

+

+ Own Id: OTP-6994 Aux Id: OTP-6933

+ + +

+ Kqueue support (kernel-poll) has been enabled on FreeBSD. + The problem with kqueue not detecting writes on a pipe on + FreeBSD was actually not a kqueue issue, but a writev on + pipes issue. Neither poll(), nor select() detected the + write when the bug hit. NetBSD and DragonFlyBSD probably + have or have had the same bug. This bug should have been + fixed in FreeBSD 6.3 and FreeBSD 7.0 thanks to + Jean-Sebastien Pedron.

+

+ Own Id: OTP-7001

+ + +
+ +
+ + +
Erts 5.5.5.5 + +
Fixed Bugs and Malfunctions + + +

+ Hanging writes on temporarily unavailable NFS + filesystems could cause the execution of (not file + related) erlang code to get blocked even though I/O + threads were used. This is now corrected.

+

+ Own Id: OTP-6907 Aux Id: seq10771

+ + +
+ +
+ +
Erts 5.5.5.4 + +
Fixed Bugs and Malfunctions + + +

+ Data passed to a driver via erlang:port_call could + be corrupted when the runtime system with SMP support was + used. (Thanks to YAMASHINA Hio.)

+

+ Own Id: OTP-6879

+ + +

+ In the SMP emulator, if several processes called + ets:update_counter/3 (even for different tables) when the + counter values exceeded 27 bits, the counter values could + be corrupted or the emulator could crash.

+

+ Own Id: OTP-6880 Aux Id: seq10760

+ + +
+ +
+ + +
Erts 5.5.5.3 + +
Fixed Bugs and Malfunctions + + +

Creating a named table using ets:new/2 or + renaming a named table using ets:rename/2 could in + rare circumstances succeed, meaning that there would be + two or more tables with the same name. Now such call will + fail with a badarg exception as it is supposed to + do.

+

ets:delete/1 used on a named table now removes + the name immediately so that a new table with the same + name can be created.

+

Turning on call trace on the internal BIF that + implements ets:delete/1 would crash the + emulator.

+

SMP emulator only: Using ets:rename/2 on a + table that ets:safe_fixtable/2 has been used on + could cause an emulator crash or undefined behaviour + because of a missing lock.

+

+ Own Id: OTP-6872 Aux Id: seq10756, seq10757

+ + +
+ +
+ +
Erts 5.5.5.2 + +
Known Bugs and Problems + + +

+ ets:select/3 on ordered_set and with a chunksize a + multiple of 1000 gave all elements instead of just 1000. + Also ets:slot/2 on ordered set could give unexpected + results on SMP emulator. Both problems are corrected.

+

+ Own Id: OTP-6842

+ + +
+ +
+ +
Erts 5.5.5.1 + +
Fixed Bugs and Malfunctions + + +

+ All exported functions in gzio.c have now been renamed to + avoid conflict with drivers that are indirectly linked + with an external zlib library.

+

+ Own Id: OTP-6816 Aux Id: OTP-6591

+ + +

+ Calling binary_to_term/1 with certain invalid binaries + would crash the emulator.

+

+ Own Id: OTP-6817

+ + +
+ + +
Improvements and New Features + + +

+ Restored speed of bit-syntax matching of 32 bits + integers.

+

+ Own Id: OTP-6789 Aux Id: seq10688

+ + +
+ +
+ +
+ Erts 5.5.5 + +
+ Fixed Bugs and Malfunctions + + +

The functions in gzio.c have been renamed to avoid + conflict with drivers that indirectly linked with an + external zlib library.

+

Own Id: OTP-6591

+ + +

The emulator without SMP support dumped core if an + async-thread finished a job after the emulator had begun + writing an .

+

Own Id: OTP-6685

+ + +

In bit syntax matching, integer fields with greater + size than 16Mb would fail to match. (Thanks to Bertil + Karlsson and Francesco Pierfederici.)

+

Matching out a 32-bit integer not aligned on a byte + boundary from a binary could cause an heap overflow (and + subsequent termination of the emulator).

+

A module that contained bit syntax construction with a + literal field size greater than 16Mb would fail to + load.

+

Several other similar bugs having to do with huge + field sizes were eliminated.

+

Attempting to construct a binary longer than 536870911 + bytes will now fail with a exception + (rather than fail in mysterious ways or construct an + binary with incorrect contents). Similarily, attempting + to match a binary longer than 536870911 bytes will now + fail (instead of producing an incorrect result). This + limitation has been documented in the Efficiency Guide. + (The limit is in the 32-bit emulator; use the 64-bit + emulator if you need to handle larger binaries than + 536870911.)

+

Own Id: OTP-6686

+ + +

Bugs in rem and div of very large numbers are corrected.

+

Own Id: OTP-6692

+ + +

didn't + allocate enough heap when a bignum was part of the result + which could cause an emulator crash.

+

Own Id: OTP-6693

+ + +

It was previously not possible to pass + the same configuration via the + command-line, as used by default.

+

A command-line argument that configure a + size of some sort can now be passed a value that equals + the size of the address space. The value used, in this + case, will be .

+

Own Id: OTP-6699

+ + +

did not update if was + invalid. is now set to if the + is invalid.

+

The driver + expects to be updated also when the + is invalid. This situation occurs seldom, but + when the runtime system has async-threads enabled and + ports are killed it can. When it occurred the runtime + system crashed.

+

Own Id: OTP-6729

+ + +
+ +
+ Improvements and New Features + + +

For scripts written using , there is a new + function , which can be used + to retrieve the pathame of the script. The documentation + has been clarified regarding pre-defined macros such as + ?MODULE and the module name.

+

Own Id: OTP-6593

+ + +

The section Guards in the chapter The Abstract Format + of the ERTS User's Guide has been updated.

+

Own Id: OTP-6600

+ + +

Corrected protocol layer flue for socket options + SO_LINGER, SO_SNDBUF and SO_RCVBUF, for SCTP.

+

Own Id: OTP-6625 Aux Id: OTP-6336

+ + +

The behaviour of the inet option {active,once} on peer + close is improved and documented.

+

Own Id: OTP-6681

+ + +

The inet option send_timeout for connection oriented + sockets is added to allow for timeouts in communicating + send requests to the underlying TCP stack.

+

Own Id: OTP-6684 Aux Id: seq10637 OTP-6681

+ + +

The command line flag , and + the environment variables , and + for the command have been + added. For more information see the + documentation.

+

Own Id: OTP-6697

+ + +

The type test has been deprecated. + is improperly named and almost + entirely undocumented.

+

Own Id: OTP-6731

+ + +
+
+ +
+ Erts 5.5.4.3 + +
+ Fixed Bugs and Malfunctions + + +

where + was a term not equal to or , + didn't fail with as it should; instead, the + failure was silently ignored. This bug was introduced in + .

+

Own Id: OTP-6627 Aux Id: OTP-6160

+ + +

The minimum and default stack size for async-threads has + been increased to 16 kilowords. This since the previous + minimum and default stack size of 8 kilowords proved to + be too small (introduced in ).

+

Own Id: OTP-6628 Aux Id: OTP-6580, Seq10633

+ + +
+ +
+ Improvements and New Features + + +

process_flag/2 accepts the new flag .

+

Own Id: OTP-6592 Aux Id: seq10555

+ + +
+
+ +
+ Erts 5.5.4.2 + +
+ Fixed Bugs and Malfunctions + + +

When a port steals control over a file descriptor from + another port, the stealing port tests if the other port + is alive. This in order to be able to give an accurate + error message. In the runtime system with SMP support, + this test was done without appropriate locks held. This + could in worst case lead to an erroneous error message; + therefore, this bug is to be considered harmless.

+

Own Id: OTP-6602

+ + +
+ +
+ Improvements and New Features + + +

The default stack size for threads in the async-thread + pool has been shrunk to 8 kilowords, i.e., 32 KB on + 32-bit architectures. This small default size has been + chosen since the amount of async-threads might be quite + large. The default stack size is enough for drivers + delivered with Erlang/OTP, but might not be sufficiently + large for other dynamically linked in drivers that use + the functionality. A suggested + stack size for threads in the async-thread pool can be + configured via the command line argument of + .

+

*** POTENTIAL INCOMPATIBILITY ***

+

Own Id: OTP-6580

+ + +
+
+ +
+ Erts 5.5.4.1 + +
+ Fixed Bugs and Malfunctions + + +

Setting the time on the system while using heart on a + linux machine where the emulator was built with + clock_gettime support (default from Linux 2.6/erts-5.5.4 + and upwards), could make the heart command fire. This was + due to bug in the heart executable which is now + corrected.

+

Own Id: OTP-6598 Aux Id: seq10614

+ + +
+
+ +
+ Erts 5.5.4 + +
+ Fixed Bugs and Malfunctions + + +

Corrected misspelling of '' in the help text + for . (Thanks to Ulf Wiger.)

+

Own Id: OTP-6433

+ + +

The MD5 calculation of a BEAM file done by + , , and by + the compiler for the default value of the + attribute have all been changed so that its result will + be the same on all platforms; modules containing funs + could get different MD5s on different platforms.

+

Own Id: OTP-6459

+ + +

The emulator could dump core while writing an + file if there were funs with a + large terms in its environment. Since there is no way to + inspect a fun's environment in the crashdump_viewer + application anyway, a variables in the environment are + now set to [] before dumping the fun. (Thanks to + Jean-Sebastien Pedron.)

+

Own Id: OTP-6504

+ + +

messages from ports + opened with the option could under + rare circumstances be delayed. This bug was present on + Erlang runtime systems without SMP support on all unix + operating systems other than SunOS.

+

Own Id: OTP-6528

+ + +

A bug in linuxthreads could cause the emulator to dump + core when dlerror() was called before the first call to + dlopen(). As a workaround the emulator always makes a + call to dlopen() on initialization when linuxthreads is + used as thread library.

+

Own Id: OTP-6530

+ + +

file:sync/1 did not do anything on Windows. Now it calls + the system function for flushing buffers + (FlushFileBuffers()). (Thanks to Matthew Sackman.)

+

Own Id: OTP-6531

+ + +

could on the runtime system with SMP + support fail with the wrong exit reason when a port + couldn't be created. When this happened the exit reason + was typically , or instead of + .

+

Own Id: OTP-6536

+ + +

The file driver (efile_drv) did not flush data written + using the option 'delayed_write' after the set timeout + time, rather at the next file operation. This bug has now + been corrected.

+

Own Id: OTP-6538

+ + +
+ +
+ Improvements and New Features + + +

An interface towards the SCTP Socket API Extensions + has been implemented.It is an Open Source patch courtesy + of Serge Aleynikov and Leonid Timochouk. The Erlang code + parts has been adapted by the OTP team, changing the + Erlang API somewhat.

+

The Erlang interface consists of the module + and an include file + for + option record definitions. The module is + documented.

+

The delivered Open Source patch, before the OTP team + rewrites, was written according to + http://tools.ietf.org/html/draft-ietf-tsvwg-sctpsocket-13 + and was claimed to work fine, tested on Linux Fedora Core + 5.0 (kernel 2.6.15-2054 or later) and on Solaris 10 and + 11. The OTP team rewrites used the same standard document + but might have accidentally broken some functionality. If + so it will soon be patched to working state. The tricky + parts in C and the general design has essentially not + changed. During the rewrites the code was hand tested on + SuSE Linux Enterprise Server 10, and briefly on Solaris + 10. Feedbach on code and docs is very much + appreciated.

+

The SCTP interface is in beta state. It has only been + hand tested and has no automatic test suites in OPT + meaning everything is most certainly not tested. Socket + active mode is broken. IPv6 is not tested. The + documentation has been reworked due to the API changes, + but has not been proofread after this.

+

Thank you from the OTP team to Serge Aleynikov and + Leonid Timochouk for a valuable contribution. We hope we + have not messed it up too much.

+

Own Id: OTP-6336

+ + +

A option is now recognized + by . {minor_version,1} will cause + floats to be encoded in an exact and more space-efficient + way compared to the previous encoding.

+

Own Id: OTP-6434

+ + +

There is a new program that can be used + for writing scripts in Erlang. Erlang scripts don't need + to be compiled and any arguments can be passed to them + without risk that they are interpreted by the Erlang + system.

+

Own Id: OTP-6505

+ + +

Setting and getting socket options in a "raw" fashion is + now allowed. Using this feature will inevitably produce + non portable code, but will allow setting ang getting + arbitrary uncommon options on TCP stacks that do have + them.

+

Own Id: OTP-6519

+ + +

Miscellaneous signal handling improvements on the Erlang + runtime system with SMP support.

+

The fallback implementation of spin locks and atomic + operations are now implemented using pthread spin locks + when pthread spin locks are found on the system.

+

The Erlang runtime system with SMP support can now run on + Linux systems that has Linuxthreads instead of NPTL + (Native POSIX Thread Library). Note that the SMP support + hasn't been as thoroughly tested with Linuxthreads as + with NPTL. A runtime system with SMP support will + therefore not be built by default on Linux when NPTL + isn't found. In order to force a build of the runtime + system with SMP support, pass + to when building OTP.

+

Own Id: OTP-6525

+ + +
+
+ +
+ Erts 5.5.3.1 + +
+ Fixed Bugs and Malfunctions + + +

could + cause the emulator with SMP support to deadlock.

+

Own Id: OTP-6431 Aux Id: OTP-6403

+ + +

The runtime system with SMP support failed to call the + driver timeout callback of ports in state closing. This + could cause ports to fail flushing their I/O queues.

+

Own Id: OTP-6432

+ + +

The message from a closed port + could arrive at the port owner before had + been removed from the result of in + the runtime system with SMP support.

+

Own Id: OTP-6437

+ + +

The async id of async jobs created via + wasn't created in a thread safe + manner in the runtime system with SMP support. This could + in worst case cause to + cancel another async job than intended.

+

Own Id: OTP-6438

+ + +

Under rare circumstances a terminating connection between + two nodes could cause an instantaneous reconnect between + the two nodes to fail on the runtime system with SMP + support.

+

Own Id: OTP-6447

+ + +

In the documentation of the driver entry field + of erts version 5.5.3 + (), the following is stated: "The + following fields are ignored if this field is equal to + ". This is a documentation bug and has been + changed to: "If this field is equal to , all the + fields following this field also have to be + , or in case it is a pointer field".

+

The runtime check for detection of old incompatible + drivers made when loading drivers has been improved. The + emulator can, however, not make sure that a driver that + doesn't use the extended driver interface 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 + interface, the emulator can verify that it isn't of an + incompatible driver version. You are therefore advised to + use the extended driver interface.

+

For more information see the and + documentation.

+

Own Id: OTP-6452 Aux Id: OTP-6330

+ + +

When terminating ports on the runtime system with SMP + support, removal of links to processes was done without + locking the link lock on processes. This could cause an + emulator crash.

+

Own Id: OTP-6475

+ + +

The emulator with SMP support could crash when a port + flushed its I/O queue by calling + from the timeout driver callback.

+

Own Id: OTP-6479

+ + +

Large exit reasons could under rare circumstances cause + the runtime system with SMP support to crash.

+

Own Id: OTP-6521

+ + +
+ +
+ Improvements and New Features + + +

Faster system calls for keeping the time accurate are + used on newer Linux kernels, which can result in a + significant speed-up of the emulator on those systems.

+

Own Id: OTP-6430

+ + +

Added number of async threads and number of scheduler + threads to the system information that can be retrieved + via . For more information see + the documentation.

+

Own Id: OTP-6440

+ + +

When is received by the runtime system + with SMP support, the is now + written by a special thread, instead of as before + directly from the signal handler.

+

Own Id: OTP-6465

+ + +

term_to_binary/2 with compression is now faster.

+

+

term_to_binary/2 now accepts the option + '' for specifying the + compression level. must be in the range 0 + (no compression) through 9 (highest compression level). + Default is 6.

+

Future compatibility bugfix: binary_to_term/1 did not + handle the and fields + correctly.

+

Own Id: OTP-6494

+ + +

Removed unnecessary reallocation when initializing + kernel-poll set.

+

Own Id: OTP-6516

+ + +
+
+ +
+ Erts 5.5.3 + +
+ Fixed Bugs and Malfunctions + + +

Node and fun table entries could under rare circumstances + be deallocated multiple times on the emulator with SMP + support.

+

Own Id: OTP-6369

+ + +

epoll_wait() can repeat entries for the same file + descriptor in the result array. This could cause the + ready_input, ready_output, or event callbacks of a driver + to unintentionally be called multiple times. We have only + noted repeated entries when an error condition has + occurred on the file descriptor. In this case, the + repeated entries should normally not be a problem for the + driver since it should detect the error and de-select the + file descriptor. Therefore this bug should be considered + harmless. The emulator now coalesce repeated entries into + one.

+

You are only affected by this bug if you are using + erts-5.5.2.* and the kernel-poll feature on linux.

+

Own Id: OTP-6376 Aux Id: OTP-6222

+ + +

If a process that was waiting in gen_tcp:accept/1 was + killed, calling gen_tcp:accept/1 again on the same listen + socket would fail with ''.

+

Own Id: OTP-6381 Aux Id: seq10535

+ + +

The emulator failed to start on Solaris 10 when + kernel-poll support was enabled and the maximum number of + filedescriptors configured was less than or equal to 256.

+

Own Id: OTP-6384 Aux Id: OTP-6222

+ + +

The R10B compiler could generate unsafe + instructions that could cause + memory corruption. (The R11B compiler does not have that + problem.) The erlang emulator will now refuse to load + R10B-compiled modules that contain such unsafe + instructions. In addition, the + beam_validator module in the compiler will also reject + such instructions (in case it is used to validate R10B + code). (Thanks to Matthew Reilly.)

+

Own Id: OTP-6386

+ + +

Process and port timers could fail to work properly on + the runtime system with SMP support. Many thanks to + Dmitriy Kargapolov and Serge Aleynikov who tracked down + this bug.

+

Own Id: OTP-6387

+ + +

Bit syntax code compiled by an R10B compiler that matched + out a floating point number would not properly check that + the floating point number was valid; if the float was, + for instance, NaN the emulator could crash.

+

Own Id: OTP-6395

+ + +

statistics(runtime) on Windows used to return the elapsed + system time for the process, instead of the user time. + Corrected. (Thanks to Robert Virding.)

+

Own Id: OTP-6407

+ + +

A loadable driver (loaded by erl_ddll) which used + driver_async() would cause the emulator to crash. (Thanks + to Dmitriy Kargapolov.)

+

Own Id: OTP-6410

+ + +

Under rare circumstances the emulator on unix platforms + could fail to terminate the Erlang port corresponding to + a port program opened with the option.

+

Own Id: OTP-6411

+ + +

A link removed via could under rare + circumstances transfer exit signals for a short period of + time after the call to had returned when + the runtime system with SMP support was used.

+

Own Id: OTP-6425 Aux Id: OTP-6160

+ + +
+ +
+ Improvements and New Features + + +

In the runtime system with SMP support, ports are now + being scheduled on the scheduler threads interleaved with + processes instead of being run in a separate I/O thread.

+

Own Id: OTP-6262

+ + +

More interfaces are added in erl_ddll, to support + different usage scenarios.

+

Own Id: OTP-6307 Aux Id: OTP-6234

+ + +

In the runtime system with SMP support, the global + I/O lock has been replaced with a more fine grained port + locking scheme. Port locking is either done on driver + level, i.e., all ports executing the same driver share a + lock, or on port level, i.e., each port has its own lock. + Currently the inet driver, the efile driver, and the + spawn driver use port level locking and all other + statically linked in drivers use driver level locking. By + default dynamically linked in drivers will use locking on + driver level. For more information on how to enable port + level locking see the and the + man pages.

+

As of erts + version 5.5.3 the driver interface has been extended. The + extended interface introduce version management, the + possibility to pass capability flags to the runtime + system at driver initialization, and some new driver API + functions. For example, the + function which can be used to determine if the driver is + run in a runtime system with SMP support or not. The + extended interface doesn't have to be used, but + dynamically linked in driver have to be + recompiled. For information see the + and the man pages.

+

NOTE: Dynamically linked in drivers + have to be recompiled.

+

*** POTENTIAL INCOMPATIBILITY ***

+

Own Id: OTP-6330 Aux Id: OTP-6262

+ + +

A test and debug feature which modifies the timing of the + runtime system has been added. For more information, see + documentation of the ]]> command line + argument of .

+

Own Id: OTP-6382

+ + +

The version of zlib (http://zlib.net) linked into + run-time system has been updated to version 1.2.3.

+

Own Id: OTP-6394

+ + +

The program now passes on the + and options to the Erlang emulator it + starts. This is mainly useful for compiling native code, + because native code must be compiled with same type of + run-time system as in which it will be run.

+

If the option is given, now + prints a warning that it is deprecated and that it will + be removed in R12B.

+

Own Id: OTP-6398

+ + +

The option of + has been removed, i.e., the + number of scheduler threads cannot be changed after + emulator boot time any more.

+

A option has been added to + . This option can be used for + blocking and unblocking multi-scheduling. For more + information see the documentation.

+

Own Id: OTP-6403

+ + +

A port program that had been started with the + option and closed one of the pipes + used for communication with the emulator caused the + emulator to continuously poll for termination of the port + program. This only became a problem when the emulator + didn't have other things to do and the port program + closed a pipe much earlier than it terminated. When the + emulator had other things to do, such as running Erlang + processes, the emulator polled for termination in between + scheduling of processes.

+

Now the emulator doesn't poll for termination of the port + program at all; instead, it waits for the child signal + from the terminated port program to arrive and then + schedules the Erlang port for termination.

+

The termination of any port programs have also been + optimized. Previously the termination of any port program + did always cause a scan of a table of the size equal to + maximum number of file descriptors. If the maximum number + of file descriptors was large, this scan could be quite + expensive. Now the search have been reduced to the set of + ports started with the option.

+

Note, all of the above only applies to Erlang emulators + on Unix platforms.

+

Own Id: OTP-6412 Aux Id: seq10194

+ + +

* BEAM: added support for floating-point exceptions on + FreeBSD (32-bit x86)

+

* SMP: made locking procedures work even when native + lock operations aren't implemented

+

* SMP: improved timing accuracy in the timer thread + (if enabled)

+

Own Id: OTP-6424

+ + +
+
+ +
+ Erts 5.5.2.2 + +
+ Fixed Bugs and Malfunctions + + +

A bug in the kernel poll implementation could cause the + emulator to omit polling for events on file descriptors. + The bug was only present when using the kernel poll + implementation based on epoll or kqueue. This bug was + introduced in erts-5.5.2.

+

Own Id: OTP-6344 Aux Id: OTP-6222

+ + +
+
+ +
+ Erts 5.5.2.1 + +
+ Fixed Bugs and Malfunctions + + +

The run_erl program now acquires its pseudo-ttys using + openpty(3), so that it will work on newer Linux + distributions that don't have the traditional pseudo-tty + devices in the file system. On platforms that don't have + openpty(3), run_erl will still search for pseudo-tty + devices in the file system.

+

The run_erl program will now wait using waitpid(3) to + prevent the program it spawned to become defunct. run_erl + will also terminate after a delay of 5 seconds (to allow + any pending output to be written to the log file) if the + spawned program terminates even if some child of it still + holds stdin and/or stdout open.

+

Own Id: OTP-6225 Aux Id: seq10500

+ + +

A bug in ordered_set ETS datatyp caused ets:select (and + match) to return faulty results when the table contained + process id's from another node.

+

Own Id: OTP-6338

+ + +
+
+ +
+ Erts 5.5.2 + +
+ Fixed Bugs and Malfunctions + + +

erlc: A typo in the help text for '-pa path' was + corrected.

+

Own Id: OTP-6218

+ + +

Failure in port command/control driver callbacks could + crash the non-SMP emulator. This bug was introduced in + the 5.5 version of erts.

+

Own Id: OTP-6224

+ + +

Erroneous "" error reports could sometimes occur + when a driver instance terminated in the ready_output() + callback of the driver. This bug was only present in + emulators that used poll(). Note, that this bug was + harmless, the only effect it had was the erroneous error + report.

+

Own Id: OTP-6229 Aux Id: OTP-3993, Seq5266, Seq7247, + OTP-4307

+ + +

The emulator could cause a type assertion failure while + writing an erl_crash.dump, causing the erl_crash.dump to + be terminated and a core dump generated.

+

Own Id: OTP-6235 Aux Id: seq10444

+ + +

The registered name of a process is now the last + observable resource removed before links and monitors are + triggered when a process terminates.

+

Previously ets tables were removed after the registered + name. This could cause problems on the runtime system + with SMP support for code that expected that ets tables + owned by a specific process had been removed if the name + of the process had been removed.

+

Own Id: OTP-6237

+ + +

Failure to fork() a new (os) process could cause the + emulator to deadlock. This bug affect all emulators with + SMP support, and emulators with async thread support on + SunOS.

+

Own Id: OTP-6241 Aux Id: OTP-3906

+ + +

Fprof traces could become truncated for the SMP emulator. + This bug has now been corrected.

+

Own Id: OTP-6246

+ + +

The undocumented functions inet:getiflist/0,1 + inet:ifget/2,3 and inet:getif/1 were completely broken on + Windows. That has been fixed.

+

Own Id: OTP-6255

+ + +

Behavior in case of disappeared nodes when using the + dist_auto_connect once got changed in R11B-1. The + timeouts regarding normal distributed operations is now + reverted to the old (pre R11B-1).

+

Own Id: OTP-6258 Aux Id: OTP-6200, seq10449

+ + +

The bsl and bsr operators could cause the emulator to + crash if given invalid arguments. (Thanks to datacompboy + and Per Gustafsson.)

+

Own Id: OTP-6259

+ + +

driver_cancel_timer() could under certain circumstances + fail to cancel the timer on the runtime system with SMP + support.

+

Own Id: OTP-6261

+ + +

A call to erlang:system_info(info) could deadlock the + runtime system with SMP support.

+

Own Id: OTP-6268

+ + +
+ +
+ Improvements and New Features + + +

Exit signals are now truly asynchronous in the runtime + system with SMP support. This simplifies locking in bifs + a lot, and makes process termination cheaper.

+

Own Id: OTP-6160

+ + +

When tracing on the runtime system with SMP support it + can be difficult to know when a trace has been delivered + to the tracer. A new built in function + has been introduced in + order to make it easier to know when the trace has been + delivered. See the erlang(3) man page for more + information.

+

Own Id: OTP-6205 Aux Id: OTP-6269

+ + +

Kernel poll support can now be combined with SMP support. + Currently the following kernel poll versions exist: + , , and . Linux + has been replaced with . Some + time in the future there will also be a kernel poll + version using Solaris event ports.

+

The "check io" implementation for unix has been + completely rewritten. The current kernel poll + implementation reduce the amount of system calls needed + compared to the old kernel poll implementation.

+

When or is used either + or is used as fallback. + Previously only could be used as fallback. + Since now can be used as fallback, kernel + poll support is now also available on newer MacOSX. Note + however, when is used as fallback, the + maximum number of file descriptors is limited to + .

+

Kernel poll support is now enabled by default if + , , or is found + when building OTP, i.e. you do not have to pass the + argument to . + As before, kernel poll is disabled by default in the + runtime system. In order to enable it, pass the + command line argument to .

+

Note: will refuse to enable kernel poll + support on FreeBSD since have problems with + (at least) pipes on all version of FreeBSD that we have + tested.

+

Own Id: OTP-6222 Aux Id: seq10380

+ + +

The module and the code in the emulator + have been completely rewritten; several bugs were fixed.

+

Own Id: OTP-6234

+ + +

The SMP emulator now avoids locking for the following + operations (thus making them as fast as in the UP + emulator): , atom comparison, atom + hashing, .

+

Own Id: OTP-6252

+ + +

There are new BIFs , + and the new option for + .

+

The module has been updated to + handle the new BIFs.

+

Own Id: OTP-6281

+ + +
+
+ +
+ Erts 5.5.1.1 + +
+ Improvements and New Features + + +

There is now an option read_packets for UDP sockets that + sets the maximum number of UDP packets that will be read + for each invocation of the socket driver.

+

Own Id: OTP-6249 Aux Id: seq10452

+ + +
+
+ +
+ Erts 5.5.1 + +
+ Fixed Bugs and Malfunctions + + +

Complex pattern matching of strings would fail in the 64 + bits emulator because of a bug in the loader. (Thanks to + Igor Goryachev.)

+

Own Id: OTP-6142

+ + +

and would be calculated incorrectly. + could in unlucky circumstances + cause a heap overflow, as could size(Binary) when size of + the binary was larger than 128Mb.

+

Own Id: OTP-6154

+ + +

erlang:display/1 displayed erroneous values for negative + integers.

+

Big integers (both positive and negative) were previously + displayed in hexadecimal form while small integers were + displayed in decimal form. All integers are now displayed + in decimal form.

+

NOTE: erlang:display/1 should only be used for debugging.

+

Own Id: OTP-6156

+ + +

A call to erlang:trace/3 with erroneous flags caused the + SMP emulator to deadlock instead of exiting the calling + process with badarg.

+

Own Id: OTP-6175

+ + +

A bug causing the emulator to hang when exiting a process + that is exception traced has been fixed.

+

Own Id: OTP-6180

+ + +

ets:rename/1 could deadlock, or crash the SMP emulator + when the table wasn't a named table.

+

ets:next/2, and ets:prev/2 could return erroneous results + on the SMP emulator.

+

Own Id: OTP-6198 Aux Id: seq10392, seq10415

+ + +

A memory allocation bug could cause the SMP emulator to + crash when a process had executed a + with a larger timeout than 10 minutes.

+

Own Id: OTP-6199

+ + +

The runtime system with SMP support did not slowly adjust + it's view of time when the system time suddenly changed.

+

Timeouts could sometimes timeout too early on the runtime + system with SMP support.

+

Own Id: OTP-6202

+ + +
+ +
+ Improvements and New Features + + +

The smp runtime system now automatically detects the + number of logical processors on MacOSX (darwin) and + OpenBSD.

+

The smp runtime system is now built by default on MacOSX + (darwin) on x86.

+

Own Id: OTP-6119

+ + +

The command line argument now take the + following options: , , or + .

+

Especially the argument is useful since + it starts the Erlang runtime system with SMP support if + it is available and more than one logical processor are + detected; otherwise, it starts the Erlang runtime system + without SMP support. For more information see the + man page.

+

Own Id: OTP-6126

+ + +

Increased the reduction cost for sending messages in the + SMP emulator so it behaves more like the non-SMP + emulator.

+

Own Id: OTP-6196

+ + +

A port running a dynamically linked-in driver that exits + due to the driver being unloaded now exits with exit + reason . Previously the port exited + with exit reason .

+

*** POTENTIAL INCOMPATIBILITY ***

+

Own Id: OTP-6204

+ + +

Changed name of the argument + to . This since the + argument so easily could be mixed up + with the argument (both returning + integers).

+

*** POTENTIAL INCOMPATIBILITY ***

+

Own Id: OTP-6208

+ + +

The changes below were made by Mikael Pettersson, HiPE.

+

HiPE runtime system:

+

Reduce overheads in the HiPE runtime system's BIF glue + code.

+

Fix bug when exceptions are thrown from BEAM to HiPE.

+

Support SPARC on Linux.

+

Support x86 on FreeBSD.

+

Floating-point exceptions:

+

Reduce overheads in checking results of floating-point + operations.

+

Minor bug fix in SSE2 floating-point exception + handling.

+

Support SSE2 floating-point exceptions on 32-bit x86 + machines.

+

Make FP exceptions work in the SMP runtime system on + FreeBSD/x86.

+

Support floating-point exceptions on SPARCs running + Linux.

+

Runtime system:

+

Minor scheduler optimisation in the non-SMP runtime + system.

+

Substantial reduction of I/O thread overheads in the + SMP runtime system if the separate timer thread is used. + (In R11B-1, the separate timer thread is not used.)

+

Own Id: OTP-6211

+ + +
+
+ +
+ ERTS 5.5 + +
+ Fixed Bugs and Malfunctions + + +

Previously and + behaved completely asynchronous. This had one undesirable + effect, though. You could never know when you were + guaranteed not to be affected by a link that you + had unlinked or a monitor that you had demonitored.

+

The new behavior of and + can be viewed as two operations + performed atomically. Asynchronously send an unlink + signal or a demonitor signal, and ignore any future + results of the link or monitor.

+

NOTE: This change can cause some obscure code + to fail which previously did not. For example, the + following code might hang:

+ ok +\011 %% We were previously guaranteed to get a down message +\011 %% (since we exited the process ourself), so we could +\011 %% in this case leave out: +\011 %% after 0 -> ok +\011 end, + ]]> +

*** POTENTIAL INCOMPATIBILITY ***

+

Own Id: OTP-5772

+ + +

Two bugs fixed: If the environment variable + was set, its contents would be appended to the end of the + command line even if the command line had an + options. Changed to place the options from + just before . Also, the and + flags no longer have any effect if placed + after .

+

Own Id: OTP-6054

+ + +
+ +
+ Improvements and New Features + + +

The documentation for writing drivers in the ERTS User's + Guide has been expanded and updated.

+

Own Id: OTP-5192

+ + +

The and operators are + now allowed to be used in guards. That also applies to + match specifications.

+

Own Id: OTP-5894 Aux Id: OTP-5149

+ + +

There is a new trace match spec function + and a corresponding trace + message that can be used to trace + on any exit from a function, both normal function return + and exception return. See the documentation for + details.

+

The trace message is now also + generated when the execution returns to a function due to + catching an exception.

+

Own Id: OTP-5956

+ + +

Erlang runtime system with SMP (symmetric multi processing) + support.

+

The runtime system with SMP support is in this release + focused on stability and there are a number of steps + with optimizations to follow before it will take + full advantage of multi processor systems. + The released system is however truly multi threaded + and you will notice increased performance + for many applications already. + We recommend that you evaluate your application on + the SMP version of the runtime system and wait for some + more optimizations before you use it in a real product. + You will then discover if there are any problems in + your application that needs to be fixed in order for + it to work properly in a multi threaded environment. + More optimized versions of the runtime system + with SMP support will be included in the R11B + maintenance releases.

+

The SMP enabled runtime system will be started if + the command line argument is passed to + the command. In order to make use of more than + one processor core, multiple scheduler threads are used. By + default, the number of scheduler threads will equal + the number of processor cores. The number of scheduler + threads can be set with the command line argument. + For more information see the man page.

+

A runtime system with SMP support is by default built on + the following platforms if posix threads, and a gcc + compiler of at least version 2.95 is found:

+ + +

Linux with at least kernel version 2.6 and the Native + POSIX Thread Library on x86, x86_64, and 32-bits + PowerPC.

+ + +

Solaris of at least version 8 on 32-bits SPARC-V9.

+ + +

MacOSX of at least version 10.4 (Darwin 8.0) on + 32-bits PowerPC.

+ + +

The runtime system with SMP support is known not + to build on:

+ + +

Windows.

+ + +

Linux with kernel versions less than 2.4, or without + the Native POSIX Thread Library.

+ + +

Other hardware platforms than x86, x86_64, 32-bits + SPARC-V9 and 32-bits PowerPC.

+ + +

Windows will be supported in a future release.

+

The runtime system with SMP support might build on other + operating systems in combination with supported hardware. + In order to force a build of a runtime system with SMP + support, pass the command line + argument to configure. Note, however, that it is not enough + that it builds. The underlying thread library and operating + system has to provide SMP support as well. If the thread + library does not distribute scheduler threads over multiple + processor cores then the runtime system will only seemingly + provide SMP support. If the runtime system is not built by + default on a specific platform, we have not tested + it on that platform.

+

NOTE: The design of SMP support for drivers is + ongoing. There will probably be incompatible driver + changes (only affecting drivers run on the runtime system + with SMP support) released as patches for R11B.

+

Potential incompatibility: Previously, specific + driver call-backs were always called from the same thread. + This is not true in the runtime system with SMP + support. Calls to call-backs will be made from different + threads, e.g., two consecutive calls to exactly the same + call-back can be made from two different threads. This + will in most cases not be a problem. All calls + to call-backs are synchronized, i.e., only one call-back + will be called at a time.

+

In the future the default behavior will probably + be the following: Calls to call-backs will, as now, be + made from different threads. Calls to call-backs in the + same driver instance will be synchronized. It + will probably be possible to configure so that all calls + to call-backs in all driver instances of a specific + driver type will be synchronized. It may be possible to + configure so that all calls to call-backs of a driver + instance or a of a specific driver type will be made from + the same thread.

+

Parallelism in the Erlang code executed is a necessity + for the Erlang runtime system to be able to take + advantage of multi-core or multi-processor hardware. + There need to be at least as many Erlang processes + runnable as processor cores for the Erlang runtime system + to be able to take advantage of all processor cores.

+

An Erlang runtime system with SMP support with only one + Erlang process runnable all the time will almost always be + slower than the same Erlang runtime system without SMP + support. This is due to thread synchronization overhead.

+

Known major bottleneck in the Erlang runtime system:

+ + +

Currently the I/O system uses one "big lock", i.e. only + one thread can do I/O at a time (with the exception of + async threads and threads created by users own linked-in + drivers). This is high on the list of things to + optimize. Note, code that does not do I/O can be executed + at the same time as one thread does I/O.

+ + +

Some pitfalls which might cause Erlang programs that work on + the non-SMP runtime system to fail on the SMP runtime + system:

+ + +

A newly spawned process will often begin executing + immediately. Code that expects that the parent process + will be able to execute for a while before the child + process begins executing is likely to fail.

+ + +

High priority processes could previously provide + mutual exclusion (bad programming style) by preventing + normal and low priority processes from being run. High + priority processes cannot be used this way to provide + mutual exclusion.

+ + +

could be used to provide some + kind of temporary mutual exclusion (also bad programming + style). cannot be used to provide + any kind of mutual exclusion.

+ + +

Obscure pitfall, only if a process being traced also + sends normal messages to the tracer:

+   The order between trace messages and normal + messages is undefined. I.e. the order between normal + messages sent from a tracee to a tracer and the trace + messages generated from the same tracee to the same + tracer is undefined. The internal order of normal + messages and the internal order of trace messages will, + of course, be preserved as before.

+ + +

The kernel poll feature is currently not supported by + the runtime system with SMP support. It will probably be + supported in a future release.

+

*** POTENTIAL INCOMPATIBILITY ***

+

Own Id: OTP-6006 Aux Id: OTP-6095

+ + +

Linked-in driver modifications.

+ + +

Linked-in drivers must be recompiled.

+ + +

The field in the type + has been removed. The reference count can be accessed + via API functions. For more information see + the man page.

+ + +

*** POTENTIAL INCOMPATIBILITY ***

+

Own Id: OTP-6095 Aux Id: OTP-6006

+ + +
+
+ +
+ ERTS 5.4.13 + +
+ Fixed Bugs and Malfunctions + + +

Large files (more than 2 GBytes) are now handled on + Solaris 8.

+

Own Id: OTP-5849 Aux Id: seq10157

+ + +

A failing bit syntax construction could fail with the + PREVIOUS exception reason that had occurred in the process + (instead of with ).

+

Own Id: OTP-5911

+ + +

When building OTP, the Kernel application was built in + both the primary and secondary bootstrap steps, which + would cause problems if OTP including its bootstrap is + checked into a version control system (such as CVS). + (Thanks to Sebastian Strollo.)

+

Own Id: OTP-5921

+ + +

and + similar expressions used to crash the emulator instead of + causing a exception. (Thanks to Matthias + Lang.)

+

Own Id: OTP-5933

+ + +

could sometimes crash the emulator + when no heap was needed.

+

Own Id: OTP-5940

+ + +

Execution of match specs could under rare circumstances + cause the emulator to dump core.

+

Execution of match specs could cause memory leaks in the + hybrid emulator.

+

Own Id: OTP-5955

+ + +

A bug in when getting info for a + function in a deleted module resulting in an emulator + crash, has been corrected.

+

Own Id: OTP-5957

+ + +

Different (and old) files in the + ERTS and Erl_Interface applications would cause build + problems on the new Intel-based iMacs. + (Thanks to Sebastion Strollo.)

+

Own Id: OTP-5967

+ + +

pthread header and library mismatch on Linux systems (at + least some SuSE and Debian) with both NPTL and + Linuxthreads libraries installed.

+

Own Id: OTP-5981

+ + +
+ +
+ Improvements and New Features + + +

The driver_set_timer did not change the previous timeout + if called a second time. Now it works as specified, + changing the timeout.

+

Own Id: OTP-5942

+ + +

The undocumented option (for the + module) did not not work correctly when + there were multiple continuation lines. (Thanks to Per + Hedeland.)

+

Own Id: OTP-5945

+ + +

The setuid_socket_wrap program was corrected to work for + C compilers that treat the type as unsigned. + (Thanks to Magnus Henoch.)

+

Own Id: OTP-5946

+ + +
+
+ +
+ ERTS 5.4.12 + +
+ Fixed Bugs and Malfunctions + + +

Fixed a minor build problem on Windows.

+

Own Id: OTP-5819 Aux Id: OTP-5382 OTP-5540 OTP-5577

+ + +

The option for was + broken on Windows.

+

Own Id: OTP-5822

+ + +

If there were user-defined variables in the boot + script, and their values were not provided using the + option, the emulator would refuse to + start with a confusing error message. Corrected to show a + clear, understandable message.

+

The module was modified to not depend + on the module, to make it possible to start + the emulator using a user-defined loader. (Thanks to + Martin Bjorklund.)

+

Own Id: OTP-5828 Aux Id: seq10151

+ + +
+ +
+ Improvements and New Features + + +

The HiPE compiler identifies more leaf functions, + giving slightly faster code.

+

Corrected problems in HiPE's coalescing register + allocating that would cause it to fail when compiling + very large functions (e.g. some of parse modules in the + Megaco application).

+

Own Id: OTP-5853

+ + +
+
+ +
+ ERTS 5.4.11 + +
+ Fixed Bugs and Malfunctions + + +

Timers could sometimes timeout too early. This bug has + now been fixed.

+

Automatic cancellation of timers created by + and + has been + introduced. Timers created with the receiver specified by a + pid, will automatically be cancelled when the receiver + exits. For more information see the man + page.

+

In order to be able to maintain a larger amount of timers + without increasing the maintenance cost, the internal + timer wheel and bif timer table have been enlarged.

+

Also a number of minor bif timer optimizations have been + implemented.

+

Own Id: OTP-5795 Aux Id: OTP-5090, seq8913, seq10139, + OTP-5782

+ + +

hanged if + referred to a process on a non-existing node with the same + nodename as the nodename of node on which the call was made. + This bug has now been fixed.

+

Own Id: OTP-5827

+ + +
+ +
+ Improvements and New Features + + +

By setting Unix environment variables, the priority for + the emulator can be lowered when it is writing crash + dumps and the time allowed for finishing writing a crash + dump can be set to a certain number of seconds. See the + documentation for in the ERTS application. + (Also, a few other previously undocumented environment + variables are now documented.)

+

Own Id: OTP-5818

+ + +

Documentation improvements:

+

- documentation for corrected

+

- command line flag added

+

- command line flags clarifications

+

- clarifications

+

Own Id: OTP-5847

+ + +
+
+ +
+ ERTS 5.4.10 + +
+ Fixed Bugs and Malfunctions + + +

-D_GNU_SOURCE is now always passed on the compile command + line on linux. This in order to ensure that all included + system headers see _GNU_SOURCE defined.

+

_GNU_SOURCE is now also defined on linux in configure + when looking for features.

+

Some minor (harmless) configure bugs were also fixed.

+

Own Id: OTP-5749

+ + +

Some compiler warnings and Dialyzer warnings were + eliminated in the Tools application.

+

When tracing to a port (which does), + there could be fake schedule out/schedule in messages + sent for a process that had exited.

+

Own Id: OTP-5757

+ + +
+ +
+ Improvements and New Features + + +

The BIFs and + has been added.

+

The BIF has been added.

+

Minor bug fix: The exception reason could be changed + to inside nested try/catch constructs if the + BIF was called with an empty + stacktrace. (Calling with an empty + stacktrace is NOT recommended.)

+

Minor bugfix: On Windows, will now + return the documented error reason + if the filename refers to a directory (it used to return + ).

+

The message in the documentation for + , description of + , was corrected.

+

Own Id: OTP-5709 Aux Id: seq10100

+ + +

The previously undocumented and UNSUPPORTED + module has been updated in an incompatible way and many + bugs have been corrected. It is now also documented.

+

*** POTENTIAL INCOMPATIBILITY ***

+

Own Id: OTP-5715

+ + +

New socket options and for + platforms that support them (currently only Linux).

+

Own Id: OTP-5756

+ + +

Only the emulator is now linked with termcap library in + order to decrease library dependencies for other otp + programs.

+

Own Id: OTP-5758

+ + +
+
+ +
+ ERTS 5.4.9.2 + +
+ Fixed Bugs and Malfunctions + + +

The native resolver has gotten an control API for + extended debugging and soft restart. It is: +



.

+

Own Id: OTP-5751 Aux Id: EABln25013

+ + +
+
+ +
+ ERTS 5.4.9.1 + +
+ Improvements and New Features + + +

On VxWorks, epmd did not handle file descriptors with + higher numbers than 63. Also, if epmd should get a file + descriptor with a number >= FD_SETSIZE, it will close a + the file descriptor and write a message to the log + (instead of mysteriously fail); the Erlang node that + tried to register will fail with a duplicate_name error + (unfortunately, epmd has no way to indicate to the Erlang + node why the register attempt failed).

+

Own Id: OTP-5716 Aux Id: seq10070

+ + +
+
+ +
+ ERTS 5.4.9 + +
+ Fixed Bugs and Malfunctions + + +

Timezone data is now initialized better. (was a problem + at least on NetBSD 2.0.2) Thanks to Rich Neswold.

+

Own Id: OTP-5621

+ + +

The hybrid-heap emulator ('erl -hybrid') is much more + stable. We have corrected all known bugs that caused it + to dump core while running our test suites.

+

Own Id: OTP-5634

+ + +

Fixed rare memory leaks in when + distributed monitors were removed.

+

Own Id: OTP-5692

+ + +

Processes were sometimes unnecessarily garbage collected + when terminating. These unnecessary garbage collections + have now been eliminated.

+

Own Id: OTP-5693

+ + +
+ +
+ Improvements and New Features + + +

The function will now run in a paged mode if + there are more than 100 processes in the system. (Thanks + to Ulf Wiger.)

+

has + been optimized and does now return exactly the same value + as . Previously + did not include + exiting processes which are included in + .

+

The flag for , which sets the maximum + number of processes allowed to exist at the same, no longer + accepts values higher than 134217727. (You will still + probably run out of memory before you'll be able to reach + that limit.)

+

Own Id: OTP-5645 Aux Id: seq9984

+ + +

The term-building driver functions + and + have been updated:

+

The ERL_DRV_FLOAT type has been added.

+

For the ERL_DRV_BINARY type, the length and offset are + now validated against the length of the driver binary.

+

The ERL_DRV_PID type is now implemented (it was + documented, but not implemented).

+

Own Id: OTP-5674

+ + +
+
+ +
+ ERTS 5.4.8 + +
+ Fixed Bugs and Malfunctions + + +

now allows other Erlang process to run + when a large table is being deleted.

+

Own Id: OTP-5572

+ + +

A bug regarding tcp sockets which results in hanging + has been corrected. To encounter + this bug you needed one process that read from a socket, + one that wrote more date than the reader read out so the + sender got suspended, and then the reader closed the + socket. (Reported and diagnosed by Alexey Shchepin.)

+

Corrected a bug in the (undocumented and unsupported) + option for + (Thanks to Claes Wikstrom and Luke Gorrie.)

+

Updated the documentation regarding the second argument to + , the to receive.

+

Own Id: OTP-5582 Aux Id: seq9839

+ + +

Erlang/OTP will now build on Mac OS X 10.4 "Tiger" (the + problem was that 10.4 has a partially implemented poll() + function that can't handle devices). Also, on Mac OS X + 10.3 "Panther", Erlang/OTP will now use select() instead + of poll() (because poll() on Mac OS X 10.3 is implemented + using select()).

+

Own Id: OTP-5595

+ + +

A bug in the file driver when opening a file in + compressed mode, and the returned allocated pointer from + the compressing library was in very high memory (>= 2GB), + causing e.g. to return + , has been corrected.

+

Own Id: OTP-5618

+ + +
+ +
+ Improvements and New Features + + +

The new fun construct creates a fun that + refers to the latest version of This syntax is + meant to replace tuple funs which have many + problems.

+

The new type test (which may be + used in guards) test whether is a fun that can be + applied with arguments. (Currently, + can also be a tuple fun.)

+

Own Id: OTP-5584

+ + +

In the HiPE application, there's a new experimental + register allocator (optimistic coalescing), and the + linear scan register allocator is now also available on + ppc. Plus lots of cleanups.

+

Minor hybrid heap corrections.

+

The maximum size of a heap used to be artificially + limited so that the size of a heap would fit in 28 bits; + that limitation could cause the emulator to terminate in + a garbage collection even if there still was available + memory. Now the largest heap size for a 32 bit CPU is + 1,699,221,830 bytes. (Thanks to Jesper Wilhelmsson.)

+

Also removed the undocumented emulator option.

+

Own Id: OTP-5596

+ + +
+
+ +
+ ERTS 5.4.7 + +
+ Fixed Bugs and Malfunctions + + +

could close unexpectedly on Linux systems. + Also, output from the emulator could be lost. Corrected.

+

Own Id: OTP-5561

+ + +
+ +
+ Improvements and New Features + + +

The option for + is now also supported on Linux.

+

Own Id: OTP-5532 Aux Id: seq9813

+ + +

The last known window size/position is now saved + correctly when is stopped with the window + minimized. A problem with the placement not being saved if + the emulator is halted or stopped from the JCL menu has also + been fixed.

+

Own Id: OTP-5544 Aux Id: OTP-5522

+ + +
+
+ +
+ ERTS 5.4.6 + +
+ Fixed Bugs and Malfunctions + + +

Some math libraries do not always throw floating-point + exceptions on errors. In order to be able to use these + libraries, floating-point errors are now more thoroughly + checked.

+

Misc floating-point fixes for Linux and MacOSX.

+

Own Id: OTP-5467

+ + +

An internal buffer was sometimes not cleared which caused + garbage to appear in error messages sent to the error + logger.

+

was sometimes clobbered which caused erroneous + error reports about errors.

+

Only emulators on unix platforms were affected by these + bugs.

+

Own Id: OTP-5492

+ + +

The ethread library now works on OpenBSD.

+

Own Id: OTP-5515

+ + +

Corrected a bug in the (undocumented and unsupported) + option for . + (Thanks to Claes Wikstrom and Luke Gorrie.)

+

Own Id: OTP-5519

+ + +
+ +
+ Improvements and New Features + + +

could cause the emulator to crash + when given invalid pids or funs.

+

Own Id: OTP-5484 Aux Id: seq9801

+ + +

Some more stability problems were fixed in the + hybrid-heap emulator.

+

Own Id: OTP-5489

+ + +

After was closed with the window minimized, it + was not possible to restart with an open + window. A temporary solution has so far been implemented + that restores the initial window settings every time + is started.

+

Own Id: OTP-5522

+ + +
+
+ +
+ ERTS 5.4.5 + +
+ Fixed Bugs and Malfunctions + + +

If a process had node links (created by + ), executing + for that process would + crash the emulator.

+

Own Id: OTP-5420

+ + +

Minor corrections to the help text printed by . The documentation for was also + slightly updated.

+

Own Id: OTP-5428

+ + +

32-bit words were used for offsets in the garbage + collector. This caused the emulator to crash on 64-bit + machines when heaps were moved more than 4 GB during + garbage collection.

+

Own Id: OTP-5430

+ + +

failed to load if optimization was + explicitly turned off.

+

Own Id: OTP-5448

+ + +

If there was a call to from any loaded + module, the returned by would + always include (even though + if was not defined).

+

Own Id: OTP-5450 Aux Id: seq9722

+ + +
+ +
+ Improvements and New Features + + +

The option for the flag has been + introduced which makes it possible to use Ctrl-C + (Ctrl-Break on Windows) to interrupt the shell process + rather than to invoke the emulator break handler. All new + options are also supported on Windows + () as of now. Furthermore, Ctrl-C on Windows has + now been reserved for copying text (what Ctrl-Ins was used + for previously). Ctrl-Break should be used for break + handling. Lastly, the documentation of the system flags has + been updated.

+

Own Id: OTP-5388

+ + +
+
+ +
+ ERTS 5.4.4 + +
+ Fixed Bugs and Malfunctions + + +

The function can now be used in + match specifications and is recognized by + and . This + addition is part of the work to "harmonize" match + specification guards with Erlang guards.

+

Own Id: OTP-5297 Aux Id: OTP-4927

+ + +

The BIF would return even if + the second argument was not a pid for living process. + Corrected to cause an exception.

+

Own Id: OTP-5324 Aux Id: seq9698

+ + +

In the 'bag' type of ets tables, elements having the same + key were supposed to be order in insertion order. The + would be wrong if a rehash occurred.

+

Own Id: OTP-5340 Aux Id: seq9704

+ + +

Linked in drivers in the Crypto and Asn1 applications + are now compiled with the and + switches on unix when the emulator has + thread support enabled.

+

Linked in drivers on MacOSX are not compiled with the + undocumented switch anymore. Thanks to + Sean Hinde who sent us a patch.

+

Linked in driver in Crypto, and port programs in SSL, now + compiles on OSF1.

+

Minor makefile improvements in Runtime_Tools.

+

Own Id: OTP-5346

+ + +

Fixed a bug in the hybrid heap in distributed send + operations.

+

Own Id: OTP-5361

+ + +

A BIF has been added. See the manual + for details. It is intended for internal system programming + only, advanced error handling.

+

Own Id: OTP-5376 Aux Id: OTP-5257

+ + +

Mikael Pettersson (HiPE) corrected a few bugs in the + emulator that caused problems when compiled with the + experimental gcc-4.0.0.

+

Own Id: OTP-5386

+ + +
+ +
+ Improvements and New Features + + +

Minor update of the internal documentation of + the protocol.

+

The listen port of has now been registered at + IANA: + http://www.iana.org/assignments/port-numbers.

+

Own Id: OTP-5234

+ + +

now works on Mac OS X and FreeBSD.

+

Own Id: OTP-5384

+ + +

A few bugs were corrected in the HiPE application.

+

Own Id: OTP-5385

+ + +
+
+ +
+ ERTS 5.4.3 + +
+ Fixed Bugs and Malfunctions + + +

Font and color preferences for now can be + saved even after the first time you run . + The window position and size is also saved. Patch from + James Hague who did all the hard work.

+

Own Id: OTP-5250

+ + +

OTP archive libraries, e.g. the + library, on MacOSX could not be used without first + rerunning on them. This bug has now been + fixed.

+

Own Id: OTP-5274

+ + +

Bugs in and on + 64-bit platforms have been fixed.

+

Own Id: OTP-5292

+ + +
+ +
+ Improvements and New Features + + +

Corrected a crash in the 64-bits emulator.

+

Corrected a problem in the hybrid heap emulator.

+

In the chapter about the abstract format in the ERTS User's + Guide, updated the last section about how the abstract + format is stored in BEAM files.

+

Own Id: OTP-5262

+ + +

The maximum number of concurrent threads in the internal + ethread thread package has been limited to 2048.

+

Own Id: OTP-5280

+ + +
+
+ +
+ ERTS 5.4.2.1 + +
+ Improvements and New Features + + +

If Erlang/OTP was installed in a short directory name, + such as , the emulator would not + start.

+

Own Id: OTP-5254

+ + +
+
+ +
+ ERTS 5.4.2 + +
+ Fixed Bugs and Malfunctions + + +

If one used and on a + non-fixed ETS table and deleted objects simultaneously, + the emulator could crash. Note that the result of such + simultaneous operations on tables that are not in a fixed + state is still undefined, but the emulator crash is, + needless to say, fixed.

+

Own Id: OTP-5209 Aux Id: seq9198

+ + +

Arithmetic with big numbers could crash the emulator.

+

The HiPE native code compiler and run-time code in the + emulator has been updated. (Note: Native code is still + not supported.)

+

Eliminated a few bugs that could crash the hybrid emulator + (which is not supported).

+

Own Id: OTP-5233 Aux Id: seq9587

+ + +
+
+ +
+ ERTS 5.4.1 + +
+ Fixed Bugs and Malfunctions + + +

The ethread library was unnecessarily rebuilt multiple + times during the build process, also a debug version of + the library was build during the install phase. These + unnecessary builds have now been removed. Note, the + content of the installed Erlang/OTP system is not + effected at all by this change.

+

Own Id: OTP-5203

+ + +

The emulator could fail to clear the memory segment + cache. This could potentially cause memory allocation to + unnecessarily fail when memory usage was close to its + maximum. This bug has now been fixed.

+

Own Id: OTP-5211

+ + +

std_alloc (std short for standard) was sometimes called + def_alloc (def short for default). std_alloc is now + everywhere referred to as std_alloc.

+

Own Id: OTP-5216

+ + +

A documentation bug has been corrected in + the documentation. It was stated that + some of the memory allocators present were by default + disabled. This is true for Erlang/OTP R9C, but is not true + for Erlang/OTP R10B. In R10B all memory allocators present + are enabled by default.

+

Own Id: OTP-5217

+ + +
+ +
+ Improvements and New Features + + +

The emulator now close all open files and sockets + immediately after receiving an USR1 signal. This causes + the emulator to unregister at as early as + possible.

+

Own Id: OTP-5221 Aux Id: OTP-4985, seq9514

+ + +

Try/catch support in the emulator slightly updated.

+

Own Id: OTP-5229

+ + +
+
+ + diff --git a/erts/doc/src/notes_history.xml b/erts/doc/src/notes_history.xml new file mode 100644 index 0000000000..cc3b938c86 --- /dev/null +++ b/erts/doc/src/notes_history.xml @@ -0,0 +1,503 @@ + + + + +
+ + 20062009 + Ericsson AB. 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. + + + + ERTS Release Notes History + otp_appnotes + nil + nil + nil + notes_history.xml +
+ +
+ ERTS 5.4 + +
+ Fixed Bugs and Malfunctions + + +

The BIF has been added to + the run-time system. It checks that is a tuple + whose first element is the atom No check + is made of the size of the tuple (because the run-time + system doesn't know anything about records).

+

Note that normally the compiler translates calls to + to code that also verify the size of the + tuple, in addition to verifying the first element. The + BIF version will be used is applied or + if the second argument is not a literal atom (e.g. a + variable or another term type, in which case the BIF will + generate a exception).

+

Own Id: OTP-4812

+ + +

Guards of mach specifications are corrected to resemble + the semantics of guards in real code more closely. The + implementation now corresponds to the documentation in + ERTS User's Guide. The following things are corrected:

+ + Guard semantics was wrong when it came to logical + operators and exceptions. + + evaluated to with bound to an + integer. + Unary + and - was not implemented. + Calling operators as Bif's was not supported by + ( etc). + Old typetests (like instead of + was not supported by + . + Semicolon (;) in guards was not supported by + . + +

*** POTENTIAL INCOMPATIBILITY ***

+

Own Id: OTP-4927

+ + +

A potential initialization failure when using threads and + elib_malloc has been removed.

+

Own Id: OTP-5125

+ + +

Several problems in the 64-bit emulator has been + corrected. For instance, the emulator could crash while + running the Debugger.

+

Own Id: OTP-5146

+ + +

The match spec parse transform no + longer accepts the and + constructs in guards for consistency with the standard + Erlang language. A future release of Erlang/OTP may allow + and in guards.

+

*** POTENTIAL INCOMPATIBILITY ***

+

Own Id: OTP-5149

+ + +

In rare circumstances in a process that has caught + exceptions and uses funs, the process would be killed + when changing code because the code server would think + that the process still held references to the funs.

+

Own Id: OTP-5153

+ + +

no longer sends any + monitoring messages to the system monitor process from + itself. This behavior is more consistent with other trace + functionality.

+

*** POTENTIAL INCOMPATIBILITY ***

+

Own Id: OTP-5183

+ + +
+ +
+ Improvements and New Features + + +

The documentation stated that + could return or that was wrong, + it always returns .

+

Own Id: OTP-4830

+ + +

The unary '+' operator has been changed to throw an + exception if its argument is not numeric (or + fail in a guard). It used its argument unchanged whatever + the type. Given the new meaning, unary '+' can now be + used to test whether a term is numeric.

+

*** POTENTIAL INCOMPATIBILITY ***

+

Own Id: OTP-4928

+ + +

Process identifiers and port identifiers have been + made more unique. Previously 18 bits were used as id in + the internal representation of process and port + identifiers. Now 28 bits are used.

+

The maximum limit on the number of concurrently existing + processes due to the representation of pids has been + increased to 268435456 processes. The same is true for + ports. This limit will at least on a 32-bit architecture be + impossible to reach due to memory shortage.

+

NOTE: By default, the , and the + , , and + libraries are now only guaranteed to be compatible with + other Erlang/OTP components from the same release. It is + possible to set each component in compatibility mode of + an earlier release, though. See the documentation for + respective component on how to set it in compatibility + mode.

+

*** POTENTIAL INCOMPATIBILITY ***

+

Own Id: OTP-4968 Aux Id: OTP-4196

+ + +

A new internal thread library for the ERTS has been + added.

+

Own Id: OTP-5048

+ + +

The system's performance could degrade severely if one + process held numerous links or monitors. The issue is + resolved.

+

Own Id: OTP-5079

+ + +

A new function, , has been added.

+

Own Id: OTP-5081 Aux Id: OTP-5136

+ + +

A new function, , has been added.

+

Own Id: OTP-5136 Aux Id: OTP-5081

+ + +

The exception code for calling a fun with wrong number of + arguments has been changed from simply to + .

+

*** POTENTIAL INCOMPATIBILITY ***

+

Own Id: OTP-5139

+ + +

The long-awaited ... construction + is included in this release. However, its use in + production code is not yet supported as there are several + known cases of legal code crashing the compiler. We plan + to release a patch to the compiler (including the + documentation) and at that time ... + will be supported.

+

Own Id: OTP-5150

+ + +
+
+ +
+ ERTS 5.3.6.6 + +
+ Fixed Bugs and Malfunctions + + +

A bug that caused an emulator crash when using system + monitor of long GC has been fixed.

+

Own Id: OTP-5123

+ + +
+
+ +
+ ERTS 5.3.6.5 + +
+ Fixed Bugs and Malfunctions + + +

and + sometimes reported erroneous values. This bug has now been + fixed.

+

Own Id: OTP-5115 Aux Id: seq9063

+ + +

There is now a packet size limit option for + sockets. See the manual for .

+

The ASN.1 BER packet decoding for sockets + can now decode indefinite length packets.

+

Own Id: OTP-5128

+ + +
+ +
+ Improvements and New Features + + +

Port index was unnecessarily incremented by port table + size when port table got full. This unnecessary increment + has now been removed.

+

Own Id: OTP-5119

+ + +
+
+ +
+ ERTS 5.3.6.3 + +
+ Fixed Bugs and Malfunctions + + +

Resolved a build problem on Mac OS 10.3 ("Panther"). + Because of a conflict with the zlib sources included in + the Erlang run-time system and the zlib library included + in Panther, linking would fail.

+

Minor optimization on all Unix systems: caching the + system name returned from the uname() system call. + (Thanks to David N. Welton.)

+

Own Id: OTP-5069

+ + +
+ +
+ Improvements and New Features + + +

The ability to set system wide options for TCP sockets is + added through the kernel application variables + and + , see the + manual page for details.

+

Own Id: OTP-5080

+ + +
+
+ +
+ ERTS 5.3.6.2 + +
+ Fixed Bugs and Malfunctions + + +

A few portability enhancements for the R9C-1 Open Source + release: The installer for Windows can now be built with + NSIS 2.0 (as well as with the NSIS 2.0b3). The driver + header files updated to allowed drivers to be built which + the MinGW compiler on Windows. Minor portability + enhancement in .

+

Own Id: OTP-4789

+ + +

Conversion of extremely small floating point numbers in + the external format (distribution) could sometimes fail + leading to unexpected closing of distribution channels, + i.e. generating nodedowns for healthy nodes.

+

Own Id: OTP-5026 Aux Id: seq8631 EABln12478

+ + +
+
+ +
+ ERTS 5.3.6.1 + +
+ Fixed Bugs and Malfunctions + + +

Conversion of extremely small floating point numbers in + the external format (distribution) could sometimes fail + leading to unexpected closing of distribution channels, + i.e. generating nodedowns for healthy nodes.

+

Own Id: OTP-5026 Aux Id: seq8631 EABln12478

+ + +
+ +
+ Improvements and New Features + + +

Remote spawn on a nonreachable node now gives warning + instead of error in the error_log.

+

Own Id: OTP-5030 Aux Id: seq8663]

+ + +
+ +
+ Known Bugs and Problems + + +

Emulator with elib_malloc enabled could hang when many + I/O threads were in use.

+

Own Id: OTP-5028 Aux Id: EABln13041, EABln12253

+ + +
+
+ +
+ ERTS 5.3.6 + +
+ Fixed Bugs and Malfunctions + + +

Distributed monitoring in combination with nodes + restarting did not behave correctly in rare + circumstances.

+

Own Id: OTP-4914

+ + +

A module containing code similar to + could not be loaded.

+

Own Id: OTP-4963 Aux Id: seq8344

+ + +

Problems fixed in : + can now be opened. Opening a FIFO will now return an error + instead of hanging the emulator. The documentation has been + updated to point out that returns + the error code when the pathname is not a + regular file (the pathname is not necessarily a directory).

+

Own Id: OTP-4992

+ + +
+ +
+ Improvements and New Features + + +

The Solaris kernel poll feature was changed from a + compile time option to a runtime option. The kernel poll + feature can be enabled, by passing the command-line + argument to an emulator (see ) + that have kernel poll support, i.e. an emulator for + Solaris 8. By default the kernel poll feature is disabled.

+

Own Id: OTP-4979 Aux Id: seq8478

+ + +

Before the Erlang emulator writes an + file (for any reason), it will close all open files and + sockets.

+

Own Id: OTP-4985 Aux Id: EABln10730, EABln11277, + EABln11279

+ + +

The switch has been added to disable time + correction in the runtime system, this should be used on + systems where one is certain no dramatic wall clock time + changes will occur and the time correction algorithm is too + costly (namely very fast Linux systems where loads of + are executed).

+

Own Id: OTP-4986

+ + +

The BIFs now take a flag + that allows changing an existing + process's minimum heap size. The actual size will only be + changed when the next garbage collection occurs.

+

Own Id: OTP-4991 Aux Id: seq8515, OTP-4987

+ + +
+
+ +
+ ERTS 5.3.4 + +
+ Improvements and New Features + + +

A possibility to make distribution messages be qued up + during running of erlang code, so that larger packages is + sent over the network is added.

+

Own Id: OTP-4916

+ + +

When code loading failed it was impossible to know + exactly what caused it, only + would be reported. Now the primitive loader lets the + error logger print an error report if a file operation + fails. All file errors except and + are reported this way.

+

Own Id: OTP-4925 Aux Id: OTP-4952

+ + +
+
+ +
+ ERTS 5.3.3 + +
+ Fixed Bugs and Malfunctions + + +

The driver for dynamically linked in drivers has been + fixed to delete loaded drivers when its Erlang server + dies. The Erlang server has also been updated to improve + the start-on-demand behaviour.

+

Own Id: OTP-4876 Aux Id: OTP-4855 seq8272

+ + +

does no longer generate an ERROR + REPORT to the error logger when the name already is + registered. If the name is already registered the process + function will crash with and that is + enough. It is up to the caller to decide if it is an + error that the name is already registered.

+

Own Id: OTP-4892

+ + +

When using , + and the GC time exceeded 1 second, it sometimes erroneously + showed up as about 4300 seconds. This bug has now been + corrected.

+

Own Id: OTP-4903 Aux Id: seq8379

+ + +
+ +
+ Improvements and New Features + + +

Starting Erlang with the flag (to ignore ^C), now + also disables the quit ('q') option in the JCL menu.

+

Own Id: OTP-4897

+ + +
+
+ +
+ ERTS 5.3.2 + +
+ Improvements and New Features + + +

The elib_malloc alternative dynamic memory allocator has + been improved to use an address order best fit strategy. + The instrumented emulator has been improved to be able to + catch memory allocations done by external libraries. The + emulator flag (stands for "relocate") makes + updates always result in an object relocation, + which significantly lessens the memory fragmentation in + certain systems. The bif can + now be called with the argument + and will return if the emulator flag + is in effect, otherwise.

+

Own Id: OTP-4838 Aux Id: seq8156

+ + +
+
+ + diff --git a/erts/doc/src/part.xml b/erts/doc/src/part.xml new file mode 100644 index 0000000000..e27b722721 --- /dev/null +++ b/erts/doc/src/part.xml @@ -0,0 +1,44 @@ + + + + +
+ + 19962009 + Ericsson AB. 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. + + + + ERTS User's Guide + Catrin Granbom + + 1997-05-15 + 4.5.2 + part.xml +
+ +

The Erlang Runtime System Application ERTS.

+ + + + + + + + + + + + diff --git a/erts/doc/src/part_notes.xml b/erts/doc/src/part_notes.xml new file mode 100644 index 0000000000..4f183999e6 --- /dev/null +++ b/erts/doc/src/part_notes.xml @@ -0,0 +1,37 @@ + + + + +
+ + 20042009 + Ericsson AB. 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. + + + + ERTS Release Notes + + + 2004-09-07 + 1.0 +
+ +

The Erlang Runtime System application ERTS.

+

For information about older versions, see + Release Notes History.

+ + + + diff --git a/erts/doc/src/part_notes_history.xml b/erts/doc/src/part_notes_history.xml new file mode 100644 index 0000000000..1b9bcca773 --- /dev/null +++ b/erts/doc/src/part_notes_history.xml @@ -0,0 +1,35 @@ + + + + +
+ + 20062009 + Ericsson AB. 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. + + + + ERTS Release Notes History + + + + +
+ +

The Erlang Runtime System application ERTS.

+ + + + diff --git a/erts/doc/src/ref_man.xml b/erts/doc/src/ref_man.xml new file mode 100644 index 0000000000..2042cf28bd --- /dev/null +++ b/erts/doc/src/ref_man.xml @@ -0,0 +1,60 @@ + + + + +
+ + 19962009 + Ericsson AB. 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. + + + + ERTS Reference Manual + Lars Thorsén + + 1997-05-15 + 4.5.2 + application.xml +
+ +

The Erlang Runtime System Application ERTS.

+ +

By default, the is only guaranteed to be compatible + with other Erlang/OTP components from the same release as + the itself. See the documentation of the system flag + +R on how to communicate + with Erlang/OTP components from earlier releases.

+ + + + + + + + + + + + + + + + + + + + + + diff --git a/erts/doc/src/run_erl.xml b/erts/doc/src/run_erl.xml new file mode 100644 index 0000000000..7bf7f559c5 --- /dev/null +++ b/erts/doc/src/run_erl.xml @@ -0,0 +1,155 @@ + + + + +
+ + 19992009 + Ericsson AB. 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. + + + + run_erl + Kent Boortz + + + + + 99-12-15 + + run_erl.xml +
+ run_erl + Redirect Erlang input and output streams on Solaris® + +

This describes the program specific to + Solaris/Linux. This program redirect the standard input and standard + output streams so that all output can be logged. It also let the + program connect to the Erlang console making it + possible to monitor and debug an embedded system remotely.

+

You can read more about the use in the .

+ + + + run_erl [-daemon] pipe_dir/ log_dir "exec command [command_arguments]" + Start the Erlang emulator without attached terminal + +

The program arguments are:

+ + -daemon + This option is highly recommended. It makes run_erl run in + the background completely detached from any controlling + terminal and the command returns to the caller immediately. + Without this option, run_erl must be started using several + tricks in the shell to detach it completely from the + terminal in use when starting it. The option must be the + first argument to run_erl on the command line. + pipe_dir + This is where to put the named pipe, usually + . It shall be suffixed by a (slash), + i.e. not , but . + log_dir + This is where the log files are written. There will be one + log file, that log progress and + warnings from the program itself and there + will be up to five log files at maximum 100KB each (both + number of logs and sizes can be + changed by environment variables, see below) with + the content of the standard streams from and to the + command. When the logs are full will delete + and reuse the oldest log file. + "exec command [command_arguments]" + In the third argument is the to execute + where everything written to stdin and stdout is logged to + . + + + + + +
+ Notes concerning the log files +

While running, run_erl (as stated earlier) sends all output, + uninterpreted, to a log file. The file is called + , where N is a number. When the log is "full", + default after 100KB, run_erl starts to log in file + , until N reaches a certain number (default + 5), where after N starts at 1 again and the oldest files start + getting overwritten. If no output comes from the erlang shell, but + the erlang machine still seems to be alive, an "ALIVE" message is + written to the log, it is a timestamp and is written, by default, + after 15 minutes of inactivity. Also, if output from erlang is + logged but it's been more than 5 minutes (default) since last time + we got anything from erlang, a timestamp is written in the + log. The "ALIVE" messages look like this:

+ + ]]> +

while the other timestamps look like this:

+ + ]]> +

The is the date and time the message is + written, default in local time (can be changed to GMT if one wants + to) and is formatted with the ANSI-C function + using the format string , which produces + messages on the line of , this can be changed, see below.

+
+ +
+ Environment variables +

The following environment variables are recognized by run_erl + and change the logging behavior. Also see the notes above to get + more info on how the log behaves.

+ + RUN_ERL_LOG_ALIVE_MINUTES + How long to wait for output (in minutes) before writing an + "ALIVE" message to the log. Default is 15, can never be less + than 1. + RUN_ERL_LOG_ACTIVITY_MINUTES + How long erlang need to be inactive before output will be + preceded with a timestamp. Default is + RUN_ERL_LOG_ALIVE_MINUTES div 3, but never less than 1. + RUN_ERL_LOG_ALIVE_FORMAT + Specifies another format string to be used in the strftime + C library call. i.e specifying this to + will give log messages with timestamps looking like + etc. See the documentation + for the C library function strftime for more + information. Default is . + RUN_ERL_LOG_ALIVE_IN_UTC + If set to anything else than "0", it will make all + times displayed by run_erl to be in UTC (GMT,CET,MET, without + DST), rather than + in local time. This does not affect data coming from erlang, + only the logs output directly by run_erl. The application + can be modified accordingly by setting the erlang + application variable to . + RUN_ERL_LOG_GENERATIONS + Controls the number of log files written before older + files are being reused. Default is 5, minimum is 2, maximum is 1000. + RUN_ERL_LOG_MAXSIZE + 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. + +
+ +
+ SEE ALSO +

start(1), start_erl(1)

+
+ + diff --git a/erts/doc/src/start.xml b/erts/doc/src/start.xml new file mode 100644 index 0000000000..5dc33deb2a --- /dev/null +++ b/erts/doc/src/start.xml @@ -0,0 +1,64 @@ + + + + +
+ + 19992009 + Ericsson AB. 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. + + + + start + Kent Boortz + + + + + 99-12-15 + + start.xml +
+ start + OTP start script example for Unix + +

This describes the script that is an example script on + how to startup the Erlang system in embedded mode on Unix.

+

You can read more about the use in the .

+ + + + start [ data_file ] + This is an example script on how to startup the Erlang system in embedded mode on Unix. + +

In the example there is one argument

+ + data_file + Optional, specifies what file + to use. + +

There is also an environment variable that can + be set prior to calling this example that set the directory + where to find the release files.

+ + + + +
+ SEE ALSO +

run_erl(1), start_erl(1)

+
+ + diff --git a/erts/doc/src/start_erl.xml b/erts/doc/src/start_erl.xml new file mode 100644 index 0000000000..21cc901f52 --- /dev/null +++ b/erts/doc/src/start_erl.xml @@ -0,0 +1,126 @@ + + + + +
+ + 19982009 + Ericsson AB. 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. + + + + start_erl + Patrik Nyblom + + + + + 98-08-05 + + start_erl.xml +
+ start_erl + Start Erlang for embedded systems on Windows NT® + +

This describes the program specific to Windows + NT. Although there exists programs with the same name on other + platforms, their functionality is not the same.

+

The program is distributed both in compiled + form (under <Erlang root>\\erts-<version>\\bin) and + in source form (under <Erlang + root>\\erts-<version>\\src). + The purpose of the source code is to make it possible to easily + customize the program for local needs, such as cyclic restart + detection etc. There is also a "make"-file, written for the + program distributed with Microsoft® Visual + C++®. The program can however be compiled with + any Win32 C compiler (possibly with slight modifications).

+

The purpose of the program is to aid release handling on + Windows NT®. The program should be called by the + program, read up the release data file + start_erl.data and start Erlang. Certain options to start_erl + are added and removed by the release handler during upgrade with + emulator restart (more specifically the option).

+ + + + start_erl [<erl options>] ++ [<start_erl options>] + Start the Erlang emulator with the correct release data + +

The program in its original form + recognizes the following options:

+ + ++ + Mandatory, delimits start_erl options from normal Erlang + options. Everything on the command line before the + is interpreted as options to be sent to the + program. Everything after is + interpreted as options to itself. + -reldir <release root> + Mandatory if the environment variable is not + specified. Tells start_erl where the root of the + release tree is placed in the file-system + (like <Erlang root>\\releases). The + file is expected to be placed in + this directory (if not otherwise specified). + -data <data file name> + Optional, specifies another data file than start_erl.data + in the <release root>. It is specified relative to the + <release root> or absolute (including drive letter + etc.). This option is used by the release handler during + upgrade and should not be used during normal + operation. The release data file should not normally be + named differently. + -bootflags <boot flags file name> + Optional, specifies a file name relative to actual release + directory (that is the subdirectory of <release + root> where the file etc. are placed). + The contents of this file is appended to the command line + when Erlang is started. This makes it easy to start the + emulator with different options for different releases. + + + + + +
+ NOTES +

As the source code is distributed, it can easily be modified to + accept other options. The program must still accept the + option with the semantics described above for the + release handler to work correctly.

+

The Erlang emulator is found by examining the registry keys for + the emulator version specified in the release data file. The new + emulator needs to be properly installed before the upgrade for + this to work.

+

Although the program is located together with files specific to + emulator version, it is not expected to be specific to the + emulator version. The release handler does not change the + option to during emulator restart. + Place the (possibly customized) program so that + it is not overwritten during upgrade.

+

The program's default options are not + sufficient for release handling. The machine + starts should be specified as the program and + the arguments should contain the followed by desired + options.

+
+ +
+ SEE ALSO +

erlsrv(1), release_handler(3)

+
+ + diff --git a/erts/doc/src/tty.xml b/erts/doc/src/tty.xml new file mode 100644 index 0000000000..23694e5965 --- /dev/null +++ b/erts/doc/src/tty.xml @@ -0,0 +1,137 @@ + + + + +
+ + 19962009 + Ericsson AB. 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. + + + + tty - A command line interface + ETX/B/SFP C. Granbom + + + EPK/TE (K. Boortz) + + 1996-11-01 + A + tty.xml +
+

is a simple command line interface program where keystrokes are collected and interpreted. Completed lines are sent to the shell for interpretation. There is a simple history mechanism, which saves previous lines. These can be edited before sending them to the shell. + is started when Erlang is started with the command:

+

erl

+

operates in one of two modes:

+ + +

normal mode, in which lines of text can be edited and sent to the shell.

+ + +

shell break mode, which allows the user to kill the current shell, start multiple shells etc. Shell break mode is started by typing Control G.

+ + + +
+ Normal Mode +

In normal mode keystrokes from the user are collected and interpreted by . Most of the emacs line editing commands are supported. The following is a complete list of the supported line editing commands.

+

Note:\011The notation means pressing the control key and the letter simultaneously. means pressing the key followed by the letter . +

+ + + Key Sequence + Function + + + C-a + Beginning of line + + + C-b + Backward character + + + M-b + Backward word + + + C-d + Delete character + + + M-d + Delete word + + + C-e + End of line + + + C-f + Forward character + + + M-f + Forward word + + + C-g + Enter shell break mode + + + C-k + Kill line + + + C-l + Redraw line + + + C-n + Fetch next line from the history buffer + + + C-p + Fetch previous line from the history buffer + + + C-t + Transpose characters + + + C-y + Insert previously killed text + + tty text editing +
+
+ +
+ Shell Break Mode +

tty enters shell break mode when you type Control G. In this mode you can:

+ + +

Kill or suspend the current shell

+ + +

Connect to a suspended shell

+ + +

Start a new shell

+ + +
+ + diff --git a/erts/doc/src/werl.xml b/erts/doc/src/werl.xml new file mode 100644 index 0000000000..1494d91da8 --- /dev/null +++ b/erts/doc/src/werl.xml @@ -0,0 +1,88 @@ + + + + +
+ + 19982009 + Ericsson AB. 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. + + + + werl + Björn Gustavsson + Bjarne Däcker + 1 + Bjarne Däcker + + 98-01-26 + A + werl.xml +
+ werl + The Erlang Emulator + +

On Windows, the preferred way to start the Erlang system for interactive use is:

+

]]>

+ +

This will start Erlang in its own window, with fully + functioning command-line editing and scrollbars. All flags + except work as they do for + the erl command.

+ +

Ctrl-C is reserved for copying text to the clipboard (Ctrl-V to paste). + To interrupt the runtime system or the shell process (depending on what + has been specified with the +B system flag), you should use Ctrl-Break.

+

In cases where you want to redirect standard input and/or + standard output or use Erlang in a pipeline, the werl is + not suitable, and the erl program should be used instead.

+ +

The werl window is in many ways modelled after the xterm + window present on other platforms, as the xterm model + fits well with line oriented command based interaction. This + means that selecting text is line oriented rather than rectangle + oriented.

+ +

To select text in the werl window , simply press and hold + the left mouse button and drag the mouse over the text you want + to select. If the selection crosses line boundaries, the + selected text will consist of complete lines where applicable + (just like in a word processor). To select more text than fits + in the window, start by selecting a small portion in the + beginning of the text you want, then use the scrollbar + to view the end of the desired selection, point to it and press + the right mouse-button. The whole area between your + first selection and the point where you right-clicked will be + included in the selection.

+ +

The selected text is copied to the clipboard by either + pressing Ctrl-C, using the menu or pressing the copy + button in the toolbar.

+ +

Pasted text is always inserted at the current prompt position + and will be interpreted by Erlang as usual keyboard input.

+ +

Previous command lines can be retrieved by pressing the Up + arrow or by pressing Ctrl-P. There is also a drop + down box in the toolbar containing the command + history. Selecting a command in the drop down box will insert it + at the prompt, just as if you used the keyboard to retrieve the + command.

+ +

Closing the werl window will stop the Erlang emulator.

+ + + + diff --git a/erts/doc/src/zlib.xml b/erts/doc/src/zlib.xml new file mode 100644 index 0000000000..9f39ac657a --- /dev/null +++ b/erts/doc/src/zlib.xml @@ -0,0 +1,606 @@ + + + + +
+ + 20052009 + Ericsson AB. 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. + + + + zlib + + + + + zlib.xml +
+ zlib + Zlib Compression interface. + +

The zlib module provides an API for the zlib library + (http://www.zlib.org). + It is used to compress and decompress data. The + data format is described by RFCs 1950 to 1952.

+

A typical (compress) usage looks like:

+ 
+Z = zlib:open(),
+ok = zlib:deflateInit(Z,default),
+
+Compress = fun(end_of_data, _Cont) -> [];
+              (Data, Cont) ->
+                 [zlib:deflate(Z, Data)|Cont(Read(),Cont)]
+           end,
+Compressed = Compress(Read(),Compress),
+Last = zlib:deflate(Z, [], finish),
+ok = zlib:deflateEnd(Z),
+zlib:close(Z),
+list_to_binary([Compressed|Last])
+

In all functions errors, {'EXIT',{Reason,Backtrace}}, + might be thrown, where Reason describes the + error. Typical reasons are:

+ + badarg + +

Bad argument

+ + data_error + +

The data contains errors

+ + stream_error + +

Inconsistent stream state

+ + einval + +

Bad value or wrong function called

+ + {need_dictionary,Adler32} + +

See inflate/2

+ + + + +
+ DATA TYPES + +iodata = iolist() | binary() + +iolist = [char() | binary() | iolist()] + a binary is allowed as the tail of the list + +zstream = a zlib stream, see open/0 +
+ + + open() -> Z + Open a stream and return a stream reference + + Z = zstream() + + +

Open a zlib stream.

+ + + + close(Z) -> ok + Close a stream + + Z = zstream() + + +

Closes the stream referenced by Z.

+ + + + deflateInit(Z) -> ok + Initialize a session for compression + + Z = zstream() + + +

Same as zlib:deflateInit(Z, default).

+ + + + deflateInit(Z, Level) -> ok + Initialize a session for compression + + Z = zstream() + Level = none | default | best_speed | best_compression | 0..9 + + +

Initialize a zlib stream for compression.

+

Level decides the compression level to be used, 0 + (none), gives no compression at all, 1 + (best_speed) gives best speed and 9 + (best_compression) gives best compression.

+ + + + deflateInit(Z, Level, Method, WindowBits, MemLevel, Strategy) -> ok + Initialize a session for compression + + Z = zstream() + Level = none | default | best_speed | best_compression | 0..9 + Method = deflated + WindowBits = 9..15|-9..-15 + MemLevel = 1..9 + Strategy = default|filtered|huffman_only + + +

Initiates a zlib stream for compression.

+

The Level parameter decides the compression level to be + used, 0 (none), gives no compression at all, 1 + (best_speed) gives best speed and 9 + (best_compression) gives best compression.

+

The Method parameter decides which compression method to use, + currently the only supported method is deflated.

+

The WindowBits 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 + deflateInit/2. A negative WindowBits + value suppresses the zlib header (and checksum) from the + stream. Note that the zlib source mentions this only as a + undocumented feature.

+

The MemLevel parameter specifies how much memory + should be allocated for the internal compression + state. MemLevel=1 uses minimum memory but is slow and + reduces compression ratio; MemLevel=9 uses maximum + memory for optimal speed. The default value is 8.

+

The Strategy parameter is used to tune the + compression algorithm. Use the value default for + normal data, filtered for data produced by a filter + (or predictor), or huffman_only to force Huffman + encoding only (no string match). Filtered data consists + mostly of small values with a somewhat random + distribution. In this case, the compression algorithm is + tuned to compress them better. The effect of + filteredis to force more Huffman coding and less + string matching; it is somewhat intermediate between + default and huffman_only. The Strategy + parameter only affects the compression ratio but not the + correctness of the compressed output even if it is not set + appropriately.

+ + + + deflate(Z, Data) -> Compressed + Compress data + + Z = zstream() + Data = iodata() + Compressed = iolist() + + +

Same as deflate(Z, Data, none).

+ + + + deflate(Z, Data, Flush) -> + Compress data + + Z = zstream() + Data = iodata() + Flush = none | sync | full | finish + Compressed = iolist() + + +

deflate/3 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.

+

If the parameter Flush is set to sync, 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.

+

If Flush is set to full, all output is flushed as with + sync, 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 full too often can seriously degrade + the compression.

+

If the parameter Flush is set to finish, + pending input is processed, pending output is flushed and + deflate/3 returns. Afterwards the only possible + operations on the stream are deflateReset/1 or deflateEnd/1.

+

Flush can be set to finish immediately after + deflateInit if all compression is to be done in one step.

+ 
+ 
+zlib:deflateInit(Z),
+B1 = zlib:deflate(Z,Data),
+B2 = zlib:deflate(Z,<< >>,finish),
+zlib:deflateEnd(Z),
+list_to_binary([B1,B2])
+ + + + deflateSetDictionary(Z, Dictionary) -> Adler32 + Initialize the compression dictionary + + Z = zstream() + Dictionary = binary() + Adler32 = integer() + + +

Initializes the compression dictionary from the given byte + sequence without producing any compressed output. This + function must be called immediately after + deflateInit/[1|2|6] or deflateReset/1, before + any call of deflate/3. The compressor and + decompressor must use exactly the same dictionary (see + inflateSetDictionary/2). The adler checksum of the + dictionary is returned.

+ + + + deflateReset(Z) -> ok + Reset the deflate session + + Z = zstream() + + +

This function is equivalent to deflateEnd/1 + followed by deflateInit/[1|2|6], but does not free + and reallocate all the internal compression state. The + stream will keep the same compression level and any other + attributes.

+ + + + deflateParams(Z, Level, Strategy) -> ok + Dynamicly update deflate parameters + + Z = zstream() + Level = none | default | best_speed | best_compression | 0..9 + Strategy = default|filtered|huffman_only + + +

Dynamically update the compression level and compression + strategy. The interpretation of Level and + Strategy is as in deflateInit/6. 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 deflate/3.

+

Before the call of deflateParams, the stream state must be set as for + a call of deflate/3, since the currently available input may have to + be compressed and flushed.

+ + + + deflateEnd(Z) -> ok + End deflate session + + Z = zstream() + + +

End the deflate session and cleans all data used. + Note that this function will throw an data_error + exception if the last call to + deflate/3 was not called with Flush set to + finish.

+ + + + inflateInit(Z) -> ok + Initialize a session for decompression + + Z = zstream() + + +

Initialize a zlib stream for decompression.

+ + + + inflateInit(Z, WindowBits) -> ok + Initialize a session for decompression + + Z = zstream() + WindowBits = 9..15|-9..-15 + + +

Initialize decompression session on zlib stream.

+

The WindowBits 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 inflateInit/1 is used. + If a compressed stream with a larger window size is + given as input, inflate() will throw the data_error + exception. A negative WindowBits value makes zlib ignore the + zlib header (and checksum) from the stream. Note that the zlib + source mentions this only as a undocumented feature.

+ + + + inflate(Z, Data) -> DeCompressed + Decompress data + + Z = zstream() + Data = iodata() + DeCompressed = iolist() + + +

inflate/2 decompresses as much data as possible. + It may some introduce some output latency (reading + input without producing any output).

+

If a preset dictionary is needed at this point (see + inflateSetDictionary below), inflate/2 throws a + {need_dictionary,Adler} exception where Adler is + the adler32 checksum of the dictionary chosen by the + compressor.

+ + + + inflateSetDictionary(Z, Dictionary) -> ok + Initialize the decompression dictionary + + Z = zstream() + Dictionary = binary() + + +

Initializes the decompression dictionary from the given + uncompressed byte sequence. This function must be called + immediately after a call of inflate/2 if this call + threw a {need_dictionary,Adler} exception. + The dictionary chosen by the + compressor can be determined from the Adler value thrown + by the call to inflate/2. The compressor and decompressor + must use exactly the same dictionary (see deflateSetDictionary/2).

+

Example:

+ 
+unpack(Z, Compressed, Dict) ->
+     case catch zlib:inflate(Z, Compressed) of
+\011  {'EXIT',{{need_dictionary,DictID},_}} ->
+  \011         zlib:inflateSetDictionary(Z, Dict),
+\011         Uncompressed = zlib:inflate(Z, []);
+\011  Uncompressed ->
+\011         Uncompressed
+     end.
+ + + + inflateReset(Z) -> ok + >Reset the inflate session + + Z = zstream() + + +

This function is equivalent to inflateEnd/1 followed + by inflateInit/1, but does not free and reallocate all + the internal decompression state. The stream will keep + attributes that may have been set by inflateInit/[1|2].

+ + + + inflateEnd(Z) -> ok + End inflate session + + Z = zstream() + + +

End the inflate session and cleans all data used. Note + that this function will throw a data_error exception + if no end of stream was found (meaning that not all data + has been uncompressed).

+ + + + setBufSize(Z, Size) -> ok + Set buffer size + + Z = zstream() + Size = integer() + + +

Sets the intermediate buffer size.

+ + + + getBufSize(Z) -> Size + Get buffer size + + Z = zstream() + Size = integer() + + +

Get the size of intermediate buffer.

+ + + + crc32(Z) -> CRC + Get current CRC + + Z = zstream() + CRC = integer() + + +

Get the current calculated CRC checksum.

+ + + + crc32(Z, Binary) -> CRC + Calculate CRC + + Z = zstream() + Binary = binary() + CRC = integer() + + +

Calculate the CRC checksum for Binary.

+ + + + crc32(Z, PrevCRC, Binary) -> CRC + Calculate CRC + + Z = zstream() + PrevCRC = integer() + Binary = binary() + CRC = integer() + + +

Update a running CRC checksum for Binary. + If Binary is the empty binary, this function returns + the required initial value for the crc.

+ 
+Crc = lists:foldl(fun(Bin,Crc0) ->  
+\011              zlib:crc32(Z, Crc0, Bin),
+\011          end, zlib:crc32(Z,<< >>), Bins)
+ + + + crc32_combine(Z, CRC1, CRC2, Size2) -> CRC + Combine two CRC's + + Z = zstream() + CRC = integer() + CRC1 = integer() + CRC2 = integer() + Size2 = integer() + + +

Combine two CRC checksums into one. For two binaries, + Bin1 and Bin2 with sizes of Size1 and + Size2, with CRC checksums CRC1 and + CRC2. crc32_combine/4 returns the CRC + checksum of <<Bin1/binary,Bin2/binary>>, requiring + only CRC1, CRC2, and Size2. +

+ + + + adler32(Z, Binary) -> Checksum + Calculate the adler checksum + + Z = zstream() + Binary = binary() + Checksum = integer() + + +

Calculate the Adler-32 checksum for Binary.

+ + + + adler32(Z, PrevAdler, Binary) -> Checksum + Calculate the adler checksum + + Z = zstream() + PrevAdler = integer() + Binary = binary() + Checksum = integer() + + +

Update a running Adler-32 checksum for Binary. + If Binary is the empty binary, this function returns + the required initial value for the checksum.

+ 
+Crc = lists:foldl(fun(Bin,Crc0) ->  
+\011              zlib:adler32(Z, Crc0, Bin),
+\011          end, zlib:adler32(Z,<< >>), Bins)
+ + + + adler32_combine(Z, Adler1, Adler2, Size2) -> Adler + Combine two Adler-32 checksums + + Z = zstream() + Adler = integer() + Adler1 = integer() + Adler2 = integer() + Size2 = integer() + + +

Combine two Adler-32 checksums into one. For two binaries, + Bin1 and Bin2 with sizes of Size1 and + Size2, with Adler-32 checksums Adler1 and + Adler2. adler32_combine/4 returns the Adler + checksum of <<Bin1/binary,Bin2/binary>>, requiring + only Adler1, Adler2, and Size2. +

+ + + + compress(Binary) -> Compressed + Compress a binary with standard zlib functionality + + Binary = Compressed = binary() + + +

Compress a binary (with zlib headers and checksum).

+ + + + uncompress(Binary) -> Decompressed + Uncompress a binary with standard zlib functionality + + Binary = Decompressed = binary() + + +

Uncompress a binary (with zlib headers and checksum).

+ + + + zip(Binary) -> Compressed + Compress a binary without the zlib headers + + Binary = Compressed = binary() + + +

Compress a binary (without zlib headers and checksum).

+ + + + unzip(Binary) -> Decompressed + Uncompress a binary without the zlib headers + + Binary = Decompressed = binary() + + +

Uncompress a binary (without zlib headers and checksum).

+ + + + gzip(Data) -> Compressed + Compress a binary with gz header + + Binary = Compressed = binary() + + +

Compress a binary (with gz headers and checksum).

+ + + + gunzip(Bin) -> Decompressed + Uncompress a binary with gz header + + Binary = Decompressed = binary() + + +

Uncompress a binary (with gz headers and checksum).

+ + + + + -- cgit v1.2.3