diff options
Diffstat (limited to 'erts/doc')
| -rw-r--r-- | erts/doc/src/driver.xml | 7 | ||||
| -rw-r--r-- | erts/doc/src/driver_entry.xml | 26 | ||||
| -rw-r--r-- | erts/doc/src/epmd.xml | 252 | ||||
| -rw-r--r-- | erts/doc/src/erl.xml | 92 | ||||
| -rw-r--r-- | erts/doc/src/erl_nif.xml | 65 | ||||
| -rw-r--r-- | erts/doc/src/erlang.xml | 371 | ||||
| -rw-r--r-- | erts/doc/src/erlc.xml | 46 | ||||
| -rw-r--r-- | erts/doc/src/escript.xml | 8 | ||||
| -rw-r--r-- | erts/doc/src/notes.xml | 1314 |
9 files changed, 1956 insertions, 225 deletions
diff --git a/erts/doc/src/driver.xml b/erts/doc/src/driver.xml index 006a6160de..db455312ec 100644 --- a/erts/doc/src/driver.xml +++ b/erts/doc/src/driver.xml @@ -196,11 +196,14 @@ static ErlDrvData start(ErlDrvPort port, char *command) <p>We call disconnect to log out from the database. (This should have been done from Erlang, but just in case.)</p> <code type="none"><![CDATA[ - static int do_disconnect(our_data_t* data, ei_x_buff* x); +static int do_disconnect(our_data_t* data, ei_x_buff* x); static void stop(ErlDrvData drv_data) { - do_disconnect((our_data_t*)drv_data, NULL); + our_data_t* data = (our_data_t*)drv_data; + + do_disconnect(data, NULL); + driver_free(data); } ]]></code> <p>We use the binary format only to return data to the emulator; diff --git a/erts/doc/src/driver_entry.xml b/erts/doc/src/driver_entry.xml index e71b48bd92..dfddbb18ea 100644 --- a/erts/doc/src/driver_entry.xml +++ b/erts/doc/src/driver_entry.xml @@ -4,7 +4,7 @@ <cref> <header> <copyright> - <year>2001</year><year>2010</year> + <year>2001</year><year>2011</year> <holder>Ericsson AB. All Rights Reserved.</holder> </copyright> <legalnotice> @@ -36,7 +36,7 @@ <description> <p>As of erts version 5.5.3 the driver interface has been extended (see <seealso marker="driver_entry#extended_marker">extended marker</seealso>). - The extended interface introduce + The extended interface introduces <seealso marker="erl_driver#version_management">version management</seealso>, the possibility to pass capability flags (see <seealso marker="driver_entry#driver_flags">driver flags</seealso>) @@ -45,21 +45,21 @@ <note> <p>Old drivers (compiled with an <c>erl_driver.h</c> from an earlier erts version than 5.5.3) have to be recompiled - (but does not have to use the extended interface).</p> + (but do not have to use the extended interface).</p> </note> <p>The <c>driver_entry</c> structure is a C struct that all erlang - drivers defines. It contains entry points for the erlang driver + drivers define. It contains entry points for the erlang driver that are called by the erlang emulator when erlang code accesses the driver.</p> <p> <marker id="emulator"></marker> The <seealso marker="driver_entry">erl_driver</seealso> driver - API functions needs a port handle + API functions need a port handle that identifies the driver instance (and the port in the emulator). This is only passed to the <c>start</c> function, but not to the other functions. The <c>start</c> function returns a driver-defined handle that is passed to the other functions. A - common practice is to have the <c>start</c> function allocating + common practice is to have the <c>start</c> function allocate some application-defined structure and stash the <c>port</c> handle in it, to use it later with the driver API functions.</p> <p>The driver call-back functions are called synchronously from the @@ -172,7 +172,7 @@ typedef struct erl_drv_entry { added to the driver list.) The driver should return 0, or if the driver can't initialize, -1.</p> </item> - <tag><marker id="start"/>int (*start)(ErlDrvPort port, char* command)</tag> + <tag><marker id="start"/>ErlDrvData (*start)(ErlDrvPort port, char* command)</tag> <item> <p>This is called when the driver is instantiated, when <c>open_port/2</c> is called. The driver should return a @@ -188,7 +188,9 @@ typedef struct erl_drv_entry { <p>This is called when the port is closed, with <c>port_close/1</c> or <c>Port ! {self(), close}</c>. Note that terminating the port owner process also closes the - port.</p> + port. If <c>drv_data</c> is a pointer to memory allocated in + <c>start</c>, then <c>stop</c> is the place to deallocate that + memory.</p> </item> <tag><marker id="output"/>void (*output)(ErlDrvData drv_data, char *buf, int len)</tag> <item> @@ -217,6 +219,10 @@ typedef struct erl_drv_entry { completes, write to the pipe (use <c>SetEvent</c> on Windows), this will make the emulator call <c>ready_input</c> or <c>ready_output</c>.</p> + <p>Spurious events may happen. That is, calls to <c>ready_input</c> + or <c>ready_output</c> even though no real events are signaled. In + reality it should be rare (and OS dependant), but a robust driver + must nevertheless be able to handle such cases.</p> </item> <tag><marker id="driver_name"/>char *driver_name</tag> <item> @@ -233,7 +239,7 @@ typedef struct erl_drv_entry { </item> <tag>void *handle</tag> <item> - <p>This field is reserved for the emulators internal use. The + <p>This field is reserved for the emulator's internal use. The emulator will modify this field; therefore, it is important that the <c>driver_entry</c> isn't declared <c>const</c>.</p> </item> @@ -397,7 +403,7 @@ typedef struct erl_drv_entry { <tag>void *handle2</tag> <item> <p> - This field is reserved for the emulators internal use. The + This field is reserved for the emulator's internal use. The emulator will modify this field; therefore, it is important that the <c>driver_entry</c> isn't declared <c>const</c>. </p> diff --git a/erts/doc/src/epmd.xml b/erts/doc/src/epmd.xml index 796ab3820b..474230cb38 100644 --- a/erts/doc/src/epmd.xml +++ b/erts/doc/src/epmd.xml @@ -4,7 +4,7 @@ <comref> <header> <copyright> - <year>1996</year><year>2009</year> + <year>1996</year><year>2010</year> <holder>Ericsson AB. All Rights Reserved.</holder> </copyright> <legalnotice> @@ -31,9 +31,23 @@ <rev>A</rev> <file>epmd.xml</file> </header> + <com>epmd</com> - <comsummary>Erlang Port Mapper Daemon </comsummary> + <comsummary> + <p>Erlang Port Mapper Daemon</p> + <taglist> + <tag><c><![CDATA[epmd [-d|-debug] [DbgExtra...] [-port No] [-daemon] [-relaxed_command_check]]]></c></tag> + <item> + <p>Starts the port mapper daemon</p> + </item> + <tag><c><![CDATA[epmd [-d|-debug] [-port No] [-names|-kill|-stop Name]]]></c></tag> + <item> + <p>Communicates with a running port mapper daemon</p> + </item> + </taglist> + </comsummary> <description> + <p>This daemon acts as a name server on all hosts involved in distributed Erlang computations. When an Erlang node starts, the node has a name and it obtains an address from the host @@ -46,48 +60,171 @@ The job of the <c><![CDATA[epmd]]></c> daemon is to keep track of which node name listens on which address. Hence, <c><![CDATA[epmd]]></c> map symbolic node names to machine addresses.</p> - <p>The daemon is started automatically by the Erlang start-up script.</p> - <p>The program <c><![CDATA[epmd]]></c> can also be used for a variety of other - purposes, for example checking the DNS (Domain Name System) - configuration of a host.</p> + + <p>The TCP/IP <c>epmd</c> daemon actually only keeps track of + the <c>Name</c> (first) part of an Erlang node name, the <c>Host</c> + part (whatever is after the <c><![CDATA[@]]></c> is implicit in the + node name where the <c>epmd</c> daemon was actually contacted, + as is the IP address where the Erlang node can be + reached. Consistent and correct TCP naming services are + therefore required for an Erlang network to function + correctly.</p> + + <taglist> + <tag>Starting the port mapper daemon</tag> + <item> + + <p>The daemon is started automatically by the <c>erl</c> + command if the node is to be distributed and there is no + running instance present. If automatically launched, + environment variables has to be used to alter the behavior of + the daemon. See the <seealso + marker="#environment_variables">Environment + variables</seealso> section below.</p> + + <p>If the -daemon argument is not given, the + <c><![CDATA[epmd]]></c> runs as a normal program with the + controlling terminal of the shell in which it is + started. Normally, it should run as a daemon.</p> + + <p>Regular start-up options are described in the + <seealso marker="#daemon_flags">Regular options</seealso> + section below.</p> + + <p>The <c>DbgExtra</c> options are described in the + <seealso marker="#debug_flags">DbgExtra options</seealso> + section below.</p> + + </item> + <tag>Communicating with a running port mapper daemon</tag> + <item> + + <p>Communicating with the running epmd daemon by means of the + <c>epmd</c> program is done primarily for debugging + purposes.</p> + + <p>The different queries are described in the <seealso + marker="#interactive_flags">Interactive options</seealso> + section below.</p> + + </item> + </taglist> </description> - <funcs> - <func> - <name>epmd [-daemon] </name> - <fsummary>Start a name server as a daemon</fsummary> - <desc> - <p>Starts a name server as a daemon. If it has no argument, the - <c><![CDATA[epmd]]></c> runs as a normal program with the controlling terminal - of the shell in which it is started. Normally, it should run as a - daemon.</p> - </desc> - </func> - <func> - <name>epmd -names</name> - <fsummary>Request the names of the registered Erlang nodes on this host</fsummary> - <desc> - <p>Requests the names of the local Erlang nodes <c><![CDATA[epmd]]></c> has - registered.</p> - </desc> - </func> - <func> - <name>epmd -kill</name> - <fsummary>Kill the <c><![CDATA[epmd]]></c>process</fsummary> - <desc> - <p>Kills the <c><![CDATA[epmd]]></c> process.</p> - </desc> - </func> - <func> - <name>epmd -help</name> - <fsummary>List options</fsummary> - <desc> - <p>Write short info about the usage including some debugging - options not listed here.</p> - </desc> - </func> - </funcs> + <section> + <marker id="daemon_flags"></marker> + <title>Regular options</title> + + <p>These options are available when starting the actual name server. The name server is normally started automatically by the <c>erl</c> command (if not already available), but it can also be started at i.e. system start-up.</p> + <taglist> + <tag><c><![CDATA[-port No]]></c></tag> + <item> + <p>Let this instance of epmd listen to another TCP port than + default 4369. This can also be set using the + <c><![CDATA[ERL_EPMD_PORT]]></c> environment variable, see the + section <seealso marker="#environment_variables">Environment + variables</seealso> below</p> + </item> + <tag><c><![CDATA[-d | -debug]]></c></tag> + <item> + + <p>Enable debug output. The more <c>-d</c> flags given, the more + debug output you will get (to a certain limit). This option is + most useful when the epmd daemon is not started as a daemon.</p> + </item> + <tag><c><![CDATA[-daemon]]></c></tag> + <item> + <p>Start epmd detached from the controlling terminal. Logging will end up in syslog when available and correctly configured. If the epmd daemon is started at boot, this option should definitely be used. It is also used when the <c>erl</c> command automatically starts <c>epmd</c>.</p> + </item> + <tag><c><![CDATA[-relaxed_command_check]]></c></tag> + <item> + <p>Start the epmd program with relaxed command checking (mostly for backward compatibility). This affects the following:</p> + <list type="bulleted"> + <item> + <p>With relaxed command checking, the <c>epmd</c> daemon can be killed from the localhost with i.e. <c>epmd -kill</c> even if there are active nodes registered. Normally only daemons with an empty node database can be killed with the <c>epmd -kill</c> command.</p> + </item> + <item> + <p>The <c>epmd -stop</c> command (and the corresponding messages to epmd, as can be given using <c>erl_interface/ei</c>) is normally always ignored, as it opens up for strange situation when two nodes of the same name can be alive at the same time. A node unregisters itself by just closing the connection to epmd, why the <c>stop</c> command was only intended for use in debugging situations.</p> + <p>With relaxed command checking enabled, you can forcibly unregister live nodes.</p> + </item> + </list> + <p>Relaxed command checking can also be enabled by setting the environment variable <c>ERL_EPMD_RELAXED_COMMAND_CHECK</c> prior to starting <c>epmd</c>.</p> + <p>Only use relaxed command checking on systems with very limited interactive usage.</p> + </item> + </taglist> + </section> <section> + <marker id="debug_flags"></marker> + <title>DbgExtra options</title> + <p>These options are purely for debugging and testing epmd clients, they should not be used in normal operation.</p> + + <taglist> + <tag><c><![CDATA[-packet_timeout Seconds]]></c></tag> + <item> + <p>Set the number of seconds a connection can be + inactive before epmd times out and closes the + connection (default 60).</p> + </item> + <tag><c><![CDATA[-delay_accept Seconds]]></c></tag> + <item> + <p>To simulate a busy server you can insert a delay between epmd + gets notified about that a new connection is requested and + when the connections gets accepted.</p> + </item> + <tag><c><![CDATA[-delay_write Seconds]]></c></tag> + <item> + <p>Also a simulation of a busy server. Inserts + a delay before a reply is sent.</p> + </item> + </taglist> + </section> + <section> + <marker id="interactive_flags"></marker> + <title>Interactive options</title> + <p>These options make <c>epmd</c> run as an interactive command displaying the results of sending queries ta an already running instance of <c>epmd</c>. The epmd contacted is always on the local node, but the <c>-port</c> option can be used to select between instances if several are running using different port on the host.</p> + <taglist> + <tag><c><![CDATA[-port No]]></c></tag> + <item> + <p>Contacts the <c>epmd</c> listening on the given TCP port number + (default 4369). This can also be set using the + <c><![CDATA[ERL_EPMD_PORT]]></c> environment variable, see the + section <seealso marker="#environment_variables">Environment + variables</seealso> below</p> + </item> + <tag><c><![CDATA[-names]]></c></tag> + <item> + <p>List names registered with the currently running epmd</p> + </item> + <tag><c><![CDATA[-kill]]></c></tag> + <item> + <p>Kill the currently running <c>epmd</c>.</p> + + <p>Killing the running <c>epmd</c> is only allowed if <c>epmd + -names</c> show an empty database or + <c>-relaxed_command_check</c> was given when the running + instance of <c>epmd</c> was started. Note that + <c>-relaxed_command_check</c> is given when starting the + daemon that is to accept killing when it has live nodes + registered. When running epmd interactively, + <c>-relaxed_command_check</c> has no effect. A daemon that is + started without relaxed command checking has to be killed + using i.e. signals or some other OS specific method if it has + active clients registered.</p> + </item> + <tag><c><![CDATA[-stop Name]]></c></tag> + <item> + <p>Forcibly unregister a live node from <c>epmd</c>'s database</p> + + <p>This command can only be used when contacting <c>epmd</c> + instances started with the <c>-relaxed_command_check</c> + flag. Note that relaxed command checking has to be enabled for + the <c>epmd</c> daemon contacted, When running epmd + interactively, + <c>-relaxed_command_check</c> has no effect.</p> + </item> + </taglist> + </section> + <section> <marker id="environment_variables"></marker> <title>Environment variables</title> <taglist> @@ -99,6 +236,15 @@ independent clusters of nodes, to co-exist on the same host. All nodes in a cluster must use the same epmd port number.</p> </item> + <tag><c><![CDATA[ERL_EPMD_RELAXED_COMMAND_CHECK]]></c></tag> + <item> + <p>If set prior to start, the <c>epmd</c> daemon will behave + as if the <c>-relaxed_command_check</c> option was given at + start-up. If consequently setting this option before starting + the Erlang virtual machine, the automatically started + <c>epmd</c> will accept the <c>-kill</c> and <c>-stop</c> + commands without restrictions.</p> + </item> </taglist> </section> @@ -116,5 +262,29 @@ silently be ignored. </p> </section> + <section> + <title>Access restrictions</title> + <p>The <c>epmd</c> daemon accepts messages from both localhost and + remote hosts. However, only the query commands are answered (and + acted upon) if the query comes from a remote host. It is always an + error to try to register a nodename if the client is not a process + located on the same host as the <c>epmd</c> instance is running on, + why such requests are considered hostile and the connection is + immediately closed.</p> + + <p>The queries accepted from remote nodes are:</p> + <list type="bulleted"> + <item> + <p>Port queries - i.e. on which port does the node with a given + name listen</p> + </item> + <item> + <p>Name listing - i.e. give a list of all names registered on + the host</p> + </item> + </list> + <p>To restrict access further, firewall software has to be used.</p> + </section> + </comref> diff --git a/erts/doc/src/erl.xml b/erts/doc/src/erl.xml index df80142ce1..1e6e290f6b 100644 --- a/erts/doc/src/erl.xml +++ b/erts/doc/src/erl.xml @@ -231,7 +231,8 @@ <tag><c><![CDATA[-detached]]></c></tag> <item> <p>Starts the Erlang runtime system detached from the system - console. Useful for running daemons and backgrounds processes.</p> + console. Useful for running daemons and backgrounds processes. Implies + <c><![CDATA[-noinput]]></c>.</p> </item> <tag><c><![CDATA[-emu_args]]></c></tag> <item> @@ -541,6 +542,28 @@ <p>Calling <c>erlang:halt/1</c> with a string argument will still produce a crash dump.</p> </item> + <tag><c><![CDATA[+e Number]]></c></tag> + <item> + <p>Set max number of ETS tables.</p> + </item> + <tag><c><![CDATA[+ec]]></c></tag> + <item> + <p>Force the <c>compressed</c> option on all ETS tables. + Only intended for test and evaluation.</p> + </item> + <tag><c><![CDATA[+fnl]]></c></tag> + <item> + <p>The VM works with file names as if they are encoded using the ISO-latin-1 encoding, disallowing Unicode characters with codepoints beyond 255. This is default on operating systems that have transparent file naming, i.e. all Unixes except MacOSX.</p> + </item> + <tag><c><![CDATA[+fnu]]></c></tag> + <item> + <p>The VM works with file names as if they are encoded using UTF-8 (or some other system specific Unicode encoding). This is the default on operating systems that enforce Unicode encoding, i.e. Windows and MacOSX.</p> + <p>By enabling Unicode file name translation on systems where this is not default, you open up to the possibility that some file names can not be interpreted by the VM and therefore will be returned to the program as raw binaries. The option is therefore considered experimental.</p> + </item> + <tag><c><![CDATA[+fna]]></c></tag> + <item> + <p>Selection between <c>+fnl</c> and <c>+fnu</c> is done based on the current locale settings in the OS, meaning that if you have set your terminal for UTF-8 encoding, the filesystem is expected to use the same encoding for filenames (use with care).</p> + </item> <tag><c><![CDATA[+hms Size]]></c></tag> <item> <p>Sets the default heap size of processes to the size @@ -603,6 +626,24 @@ <item> <p>Force ets memory block to be moved on realloc.</p> </item> + <tag><marker id="+rg"><c><![CDATA[+rg ReaderGroupsLimit]]></c></marker></tag> + <item> + <p>Limits the amount of reader groups used by read/write locks + optimized for read operations in the Erlang runtime system. By + default the reader groups limit equals 8.</p> + <p>When the amount of schedulers is less than or equal to the reader + groups limit, each scheduler has its own reader group. When the + amount of schedulers is larger than the reader groups limit, + schedulers share reader groups. Shared reader groups degrades + read lock and read unlock performance while a large amount of + reader groups degrades write lock performance, so the limit is a + tradeoff between performance for read operations and performance + for write operations. Each reader group currently consumes 64 byte + in each read/write lock. Also note that a runtime system using + shared reader groups benefits from <seealso marker="#+sbt">binding + schedulers to logical processors</seealso>, since the reader groups + are distributed better between schedulers.</p> + </item> <tag><marker id="+S"><c><![CDATA[+S Schedulers:SchedulerOnline]]></c></marker></tag> <item> <p>Sets the amount of scheduler threads to create and scheduler @@ -667,8 +708,8 @@ <seealso marker="erlang#system_flag_scheduler_bind_type">erlang:system_flag(scheduler_bind_type, default_bind)</seealso>. </p></item> </taglist> - <p>Binding of schedulers are currently only supported on newer - Linux and Solaris systems.</p> + <p>Binding of schedulers is currently only supported on newer + Linux, Solaris, FreeBSD, and Windows systems.</p> <p>If no CPU topology is available when the <c>+sbt</c> flag is processed and <c>BindType</c> is any other type than <c>u</c>, the runtime system will fail to start. CPU @@ -813,14 +854,28 @@ <p>For more information, see <seealso marker="erlang#system_flag_cpu_topology">erlang:system_flag(cpu_topology, CpuTopology)</seealso>.</p> </item> + <tag><marker id="+swt"><c>+swt very_low|low|medium|high|very_high</c></marker></tag> + <item> + <p>Set scheduler wakeup threshold. Default is <c>medium</c>. + The threshold determines when to wake up sleeping schedulers + when more work than can be handled by currently awake schedulers + exist. A low threshold will cause earlier wakeups, and a high + threshold will cause later wakeups. Early wakeups will + distribute work over multiple schedulers faster, but work will + more easily bounce between schedulers. + </p> + <p><em>NOTE:</em> This flag may be removed or changed at any time + without prior notice. + </p> + </item> + <tag><marker id="sched_thread_stack_size"><c><![CDATA[+sss size]]></c></marker></tag> + <item> + <p>Suggested stack size, in kilowords, for scheduler threads. + Valid range is 4-8192 kilowords. The default stack size + is OS dependent.</p> + </item> </taglist> </item> - <tag><marker id="sched_thread_stack_size"><c><![CDATA[+sss size]]></c></marker></tag> - <item> - <p>Suggested stack size, in kilowords, for scheduler threads. - Valid range is 4-8192 kilowords. The default stack size - is OS dependent.</p> - </item> <tag><marker id="+t"><c><![CDATA[+t size]]></c></marker></tag> <item> <p>Set the maximum number of atoms the VM can handle. Default is 1048576.</p> @@ -874,6 +929,25 @@ <seealso marker="kernel:error_logger#warning_map/0">error_logger(3)</seealso> for further information.</p> </item> + <tag><c><![CDATA[+zFlag Value]]></c></tag> + <item> + <p>Miscellaneous flags.</p> + <taglist> + <tag><marker id="+zdbbl"><c>+zdbbl size</c></marker></tag> + <item> + <p>Set the distribution buffer busy limit + (<seealso marker="erlang#system_info_dist_buf_busy_limit">dist_buf_busy_limit</seealso>) + in kilobytes. Valid range is 1-2097151. Default is 1024.</p> + <p>A larger buffer limit will allow processes to buffer + more outgoing messages over the distribution. When the + buffer limit has been reached, sending processes will be + suspended until the buffer size has shrunk. The buffer + limit is per distribution channel. A higher limit will + give lower latency and higher throughput at the expense + of higher memory usage.</p> + </item> + </taglist> + </item> </taglist> </section> diff --git a/erts/doc/src/erl_nif.xml b/erts/doc/src/erl_nif.xml index f7b7b2f346..5987ddbd5e 100644 --- a/erts/doc/src/erl_nif.xml +++ b/erts/doc/src/erl_nif.xml @@ -4,7 +4,7 @@ <cref> <header> <copyright> - <year>2001</year><year>2009</year> + <year>2001</year><year>2011</year> <holder>Ericsson AB. All Rights Reserved.</holder> </copyright> <legalnotice> @@ -34,11 +34,10 @@ <lib>erl_nif</lib> <libsummary>API functions for an Erlang NIF library</libsummary> <description> - <warning><p>The NIF concept was introduced in R13B03 as an - EXPERIMENTAL feature. The interfaces may be changed in any way - in coming releases. The plan is however to lift the experimental label and - maintain interface backward compatibility from R14B.</p> - <p>Incompatible changes in <em>R14A</em>:</p> + <note><p>The NIF concept is officially supported from R14B. NIF source code + written for earlier experimental versions might need adaption to run on R14B.</p> + <p>No incompatible changes between <em>R14B</em> and R14A.</p> + <p>Incompatible changes between <em>R14A</em> and R13B04:</p> <list> <item>Environment argument removed for <c>enif_alloc</c>, <c>enif_realloc</c>, <c>enif_free</c>, <c>enif_alloc_binary</c>, @@ -50,14 +49,14 @@ <item>Module argument added to <c>enif_open_resource_type</c> while changing name spaces of resource types from global to module local.</item> </list> - <p>Incompatible changes in <em>R13B04</em>:</p> + <p>Incompatible changes between <em>R13B04</em> and R13B03:</p> <list> <item>The function prototypes of the NIFs have changed to expect <c>argc</c> and <c>argv</c> arguments. The arity of a NIF is by that no longer limited to 3.</item> <item><c>enif_get_data</c> renamed as <c>enif_priv_data</c>.</item> <item><c>enif_make_string</c> got a third argument for character encoding.</item> </list> - </warning> + </note> <p>A NIF library contains native implementation of some functions of an Erlang module. The native implemented functions (NIFs) are @@ -456,12 +455,16 @@ typedef enum { to return information about the runtime system. Contains currently the exact same content as <seealso marker="erl_driver#ErlDrvSysInfo">ErlDrvSysInfo</seealso>.</p> </item> + <tag><marker id="ErlNifSInt64"/>ErlNifSInt64</tag> + <item><p>A native signed 64-bit integer type.</p></item> + <tag><marker id="ErlNifUInt64"/>ErlNifUInt64</tag> + <item><p>A native unsigned 64-bit integer type.</p></item> </taglist> </section> <funcs> - <func><name><ret>void*</ret><nametext>enif_alloc(ErlNifEnv* env, size_t size)</nametext></name> + <func><name><ret>void*</ret><nametext>enif_alloc(size_t size)</nametext></name> <fsummary>Allocate dynamic memory.</fsummary> <desc><p>Allocate memory of <c>size</c> bytes. Return NULL if allocation failed.</p></desc> </func> @@ -536,7 +539,7 @@ typedef enum { <desc><p>Same as <seealso marker="erl_driver#erl_drv_equal_tids">erl_drv_equal_tids</seealso>. </p></desc> </func> - <func><name><ret>void</ret><nametext>enif_free(ErlNifEnv* env, void* ptr)</nametext></name> + <func><name><ret>void</ret><nametext>enif_free(void* ptr)</nametext></name> <fsummary>Free dynamic memory</fsummary> <desc><p>Free memory allocated by <c>enif_alloc</c>.</p></desc> </func> @@ -571,7 +574,13 @@ typedef enum { <fsummary>Read an integer term</fsummary> <desc><p>Set <c>*ip</c> to the integer value of <c>term</c>. Return true on success or false if <c>term</c> is not an - integer or is outside the bounds of type <c>int</c></p></desc> + integer or is outside the bounds of type <c>int</c>.</p></desc> + </func> + <func><name><ret>int</ret><nametext>enif_get_int64(ErlNifEnv* env, ERL_NIF_TERM term, ErlNifSInt64* ip)</nametext></name> + <fsummary>Read a 64-bit integer term</fsummary> + <desc><p>Set <c>*ip</c> to the integer value of + <c>term</c>. Return true on success or false if <c>term</c> is not an + integer or is outside the bounds of a signed 64-bit integer.</p></desc> </func> <func><name><ret>int</ret><nametext>enif_get_local_pid(ErlNifEnv* env, ERL_NIF_TERM term, ErlNifPid* pid)</nametext></name> <fsummary>Read an local pid term</fsummary> @@ -633,7 +642,12 @@ typedef enum { return true, or return false if <c>term</c> is not an unsigned integer or is outside the bounds of type <c>unsigned int</c>.</p></desc> </func> - + <func><name><ret>int</ret><nametext>enif_get_uint64(ErlNifEnv* env, ERL_NIF_TERM term, ErlNifUInt64* ip)</nametext></name> + <fsummary>Read an unsigned 64-bit integer term.</fsummary> + <desc><p>Set <c>*ip</c> to the unsigned integer value of <c>term</c> and + return true, or return false if <c>term</c> is not an unsigned integer or + is outside the bounds of an unsigned 64-bit integer.</p></desc> + </func> <func><name><ret>int</ret><nametext>enif_get_ulong(ErlNifEnv* env, ERL_NIF_TERM term, unsigned long* ip)</nametext></name> <fsummary>Read an unsigned integer term.</fsummary> <desc><p>Set <c>*ip</c> to the unsigned long integer value of <c>term</c> @@ -758,6 +772,10 @@ typedef enum { <fsummary>Create an integer term</fsummary> <desc><p>Create an integer term.</p></desc> </func> + <func><name><ret>ERL_NIF_TERM</ret><nametext>enif_make_int64(ErlNifEnv* env, ErlNifSInt64 i)</nametext></name> + <fsummary>Create an integer term</fsummary> + <desc><p>Create an integer term from a signed 64-bit integer.</p></desc> + </func> <func><name><ret>ERL_NIF_TERM</ret><nametext>enif_make_list(ErlNifEnv* env, unsigned cnt, ...)</nametext></name> <fsummary>Create a list term.</fsummary> <desc><p>Create an ordinary list term of length <c>cnt</c>. Expects @@ -839,11 +857,6 @@ typedef enum { <seealso marker="#enif_release_resource">enif_release_resource</seealso>.</p> </desc> </func> - <func><name><ret>ErlNifPid*</ret><nametext>enif_self(ErlNifEnv* caller_env, ErlNifPid* pid)</nametext></name> - <fsummary>Get the pid of the calling process.</fsummary> - <desc><p>Initialize the pid variable <c>*pid</c> to represent the - calling process. Return <c>pid</c>.</p></desc> - </func> <func><name><ret>ERL_NIF_TERM</ret><nametext>enif_make_string(ErlNifEnv* env, const char* string, ErlNifCharEncoding encoding)</nametext></name> <fsummary>Create a string.</fsummary> <desc><p>Create a list containing the characters of the @@ -894,6 +907,10 @@ typedef enum { <fsummary>Create an unsigned integer term</fsummary> <desc><p>Create an integer term from an <c>unsigned int</c>.</p></desc> </func> + <func><name><ret>ERL_NIF_TERM</ret><nametext>enif_make_uint64(ErlNifEnv* env, ErlNifUInt64 i)</nametext></name> + <fsummary>Create an unsigned integer term</fsummary> + <desc><p>Create an integer term from an unsigned 64-bit integer.</p></desc> + </func> <func><name><ret>ERL_NIF_TERM</ret><nametext>enif_make_ulong(ErlNifEnv* env, unsigned long i)</nametext></name> <fsummary>Create an integer term from an unsigned long int</fsummary> <desc><p>Create an integer term from an <c>unsigned long int</c>.</p></desc> @@ -958,11 +975,12 @@ typedef enum { <c>reload</c> or <c>upgrade</c>.</p> <p>Was previously named <c>enif_get_data</c>.</p></desc> </func> - <func><name><ret>void</ret><nametext>enif_realloc_binary(ErlNifBinary* bin, size_t size)</nametext></name> + <func><name><ret>int</ret><nametext>enif_realloc_binary(ErlNifBinary* bin, size_t size)</nametext></name> <fsummary>Change the size of a binary.</fsummary> <desc><p>Change the size of a binary <c>bin</c>. The source binary may be read-only, in which case it will be left untouched and - a mutable copy is allocated and assigned to <c>*bin</c>.</p></desc> + a mutable copy is allocated and assigned to <c>*bin</c>. Return true on success, + false if memory allocation failed.</p></desc> </func> <func><name><ret>void</ret><nametext>enif_release_binary(ErlNifBinary* bin)</nametext></name> <fsummary>Release a binary.</fsummary> @@ -1019,7 +1037,12 @@ typedef enum { <desc><p>Same as <seealso marker="erl_driver#erl_drv_rwlock_tryrwlock">erl_drv_rwlock_tryrwlock</seealso>. </p></desc> </func> - <func><name><ret>unsigned</ret><nametext>enif_send(ErlNifEnv* env, ErlNifPid* to_pid, ErlNifEnv* msg_env, ERL_NIF_TERM msg)</nametext></name> + <func><name><ret>ErlNifPid*</ret><nametext>enif_self(ErlNifEnv* caller_env, ErlNifPid* pid)</nametext></name> + <fsummary>Get the pid of the calling process.</fsummary> + <desc><p>Initialize the pid variable <c>*pid</c> to represent the + calling process. Return <c>pid</c>.</p></desc> + </func> + <func><name><ret>int</ret><nametext>enif_send(ErlNifEnv* env, ErlNifPid* to_pid, ErlNifEnv* msg_env, ERL_NIF_TERM msg)</nametext></name> <fsummary>Send a message to a process.</fsummary> <desc><p>Send a message to a process.</p> <taglist> @@ -1108,7 +1131,7 @@ typedef enum { </funcs> <section> <title>SEE ALSO</title> - <p><seealso marker="erlang#load_nif-2">load_nif(3)</seealso></p> + <p><seealso marker="erlang#load_nif-2">erlang:load_nif/2</seealso></p> </section> </cref> diff --git a/erts/doc/src/erlang.xml b/erts/doc/src/erlang.xml index 6f30c7fb21..c3f06982f5 100644 --- a/erts/doc/src/erlang.xml +++ b/erts/doc/src/erlang.xml @@ -80,7 +80,7 @@ iolist() = [char() | binary() | iolist()] </desc> </func> <func> - <name>adler32(Data) -> int()</name> + <name>erlang:adler32(Data) -> int()</name> <fsummary>Compute adler32 checksum</fsummary> <type> <v>Data = iodata()</v> @@ -90,7 +90,7 @@ iolist() = [char() | binary() | iolist()] </desc> </func> <func> - <name>adler32(OldAdler, Data) -> int()</name> + <name>erlang:adler32(OldAdler, Data) -> int()</name> <fsummary>Compute adler32 checksum</fsummary> <type> <v>OldAdler = int()</v> @@ -102,17 +102,17 @@ iolist() = [char() | binary() | iolist()] <c>Data</c>.</p> <p>The following code:</p> <code> - X = adler32(Data1), - Y = adler32(X,Data2). + X = erlang:adler32(Data1), + Y = erlang:adler32(X,Data2). </code> <p>- would assign the same value to <c>Y</c> as this would:</p> <code> - Y = adler32([Data1,Data2]). + Y = erlang:adler32([Data1,Data2]). </code> </desc> </func> <func> - <name>adler32_combine(FirstAdler, SecondAdler, SecondSize) -> int()</name> + <name>erlang:adler32_combine(FirstAdler, SecondAdler, SecondSize) -> int()</name> <fsummary>Combine two adler32 checksums</fsummary> <type> <v>FirstAdler = SecondAdler = int()</v> @@ -124,14 +124,14 @@ iolist() = [char() | binary() | iolist()] the second checksum to be known.</p> <p>The following code:</p> <code> - Y = adler32(Data1), - Z = adler32(Y,Data2). + Y = erlang:adler32(Data1), + Z = erlang:adler32(Y,Data2). </code> <p>- would assign the same value to <c>Z</c> as this would:</p> <code> - X = adler32(Data1), - Y = adler32(Data2), - Z = adler32_combine(X,Y,iolist_size(Data2)). + X = erlang:adler32(Data1), + Y = erlang:adler32(Data2), + Z = erlang:adler32_combine(X,Y,iolist_size(Data2)). </code> </desc> </func> @@ -147,7 +147,7 @@ iolist() = [char() | binary() | iolist()] <c>Tuple1</c>, and contains the elements in <c>Tuple1</c> followed by <c>Term</c> as the last element. Semantically equivalent to - <c>list_to_tuple(tuple_to_list(Tuple ++ [Term])</c>, but much + <c>list_to_tuple(tuple_to_list(Tuple) ++ [Term])</c>, but much faster.</p> <pre> > <input>erlang:append_element({one, two}, three).</input> @@ -499,7 +499,7 @@ iolist() = [char() | binary() | iolist()] <name>erlang:cancel_timer(TimerRef) -> Time | false</name> <fsummary>Cancel a timer</fsummary> <type> - <v>TimerRef = ref()</v> + <v>TimerRef = reference()</v> <v>Time = int()</v> </type> <desc> @@ -553,7 +553,7 @@ false</pre> </desc> </func> <func> - <name>crc32(Data) -> int()</name> + <name>erlang:crc32(Data) -> int()</name> <fsummary>Compute crc32 (IEEE 802.3) checksum</fsummary> <type> <v>Data = iodata()</v> @@ -563,7 +563,7 @@ false</pre> </desc> </func> <func> - <name>crc32(OldCrc, Data) -> int()</name> + <name>erlang:crc32(OldCrc, Data) -> int()</name> <fsummary>Compute crc32 (IEEE 802.3) checksum</fsummary> <type> <v>OldCrc = int()</v> @@ -575,17 +575,17 @@ false</pre> <c>Data</c>.</p> <p>The following code:</p> <code> - X = crc32(Data1), - Y = crc32(X,Data2). + X = erlang:crc32(Data1), + Y = erlang:crc32(X,Data2). </code> <p>- would assign the same value to <c>Y</c> as this would:</p> <code> - Y = crc32([Data1,Data2]). + Y = erlang:crc32([Data1,Data2]). </code> </desc> </func> <func> - <name>crc32_combine(FirstCrc, SecondCrc, SecondSize) -> int()</name> + <name>erlang:crc32_combine(FirstCrc, SecondCrc, SecondSize) -> int()</name> <fsummary>Combine two crc32 (IEEE 802.3) checksums</fsummary> <type> <v>FirstCrc = SecondCrc = int()</v> @@ -597,14 +597,14 @@ false</pre> the second checksum to be known.</p> <p>The following code:</p> <code> - Y = crc32(Data1), - Z = crc32(Y,Data2). + Y = erlang:crc32(Data1), + Z = erlang:crc32(Y,Data2). </code> <p>- would assign the same value to <c>Z</c> as this would:</p> <code> - X = crc32(Data1), - Y = crc32(Data2), - Z = crc32_combine(X,Y,iolist_size(Data2)). + X = erlang:crc32(Data1), + Y = erlang:crc32(Data2), + Z = erlang:crc32_combine(X,Y,iolist_size(Data2)). </code> </desc> </func> @@ -624,7 +624,7 @@ false</pre> </desc> </func> <func> - <name>decode_packet(Type,Bin,Options) -> {ok,Packet,Rest} | {more,Length} | {error,Reason}</name> + <name>erlang:decode_packet(Type,Bin,Options) -> {ok,Packet,Rest} | {more,Length} | {error,Reason}</name> <fsummary>Extracts a protocol packet from a binary</fsummary> <type> <v>Bin = binary()</v> @@ -760,18 +760,18 @@ false</pre> </desc> </func> <func> - <name>erlang:demonitor(MonitorRef) -> true</name> + <name>demonitor(MonitorRef) -> true</name> <fsummary>Stop monitoring</fsummary> <type> - <v>MonitorRef = ref()</v> + <v>MonitorRef = reference()</v> </type> <desc> <p>If <c>MonitorRef</c> is a reference which the calling process obtained by calling - <seealso marker="#monitor/2">erlang:monitor/2</seealso>, + <seealso marker="#monitor/2">monitor/2</seealso>, this monitoring is turned off. If the monitoring is already turned off, nothing happens.</p> - <p>Once <c>erlang:demonitor(MonitorRef)</c> has returned it is + <p>Once <c>demonitor(MonitorRef)</c> has returned it is guaranteed that no <c>{'DOWN', MonitorRef, _, _, _}</c> message due to the monitor will be placed in the callers message queue in the future. A <c>{'DOWN', MonitorRef, _, _, _}</c> message @@ -779,10 +779,10 @@ false</pre> the call, though. Therefore, in most cases, it is advisable to remove such a <c>'DOWN'</c> message from the message queue after monitoring has been stopped. - <seealso marker="#demonitor/2">erlang:demonitor(MonitorRef, [flush])</seealso> can be used instead of - <c>erlang:demonitor(MonitorRef)</c> if this cleanup is wanted.</p> + <seealso marker="#demonitor/2">demonitor(MonitorRef, [flush])</seealso> can be used instead of + <c>demonitor(MonitorRef)</c> if this cleanup is wanted.</p> <note> - <p>Prior to OTP release R11B (erts version 5.5) <c>erlang:demonitor/1</c> + <p>Prior to OTP release R11B (erts version 5.5) <c>demonitor/1</c> behaved completely asynchronous, i.e., the monitor was active until the "demonitor signal" reached the monitored entity. This had one undesirable effect, though. You could never know when @@ -800,10 +800,10 @@ false</pre> </desc> </func> <func> - <name>erlang:demonitor(MonitorRef, OptionList) -> true|false</name> + <name>demonitor(MonitorRef, OptionList) -> true|false</name> <fsummary>Stop monitoring</fsummary> <type> - <v>MonitorRef = ref()</v> + <v>MonitorRef = reference()</v> <v>OptionList = [Option]</v> <v>Option = flush</v> <v>Option = info</v> @@ -812,8 +812,8 @@ false</pre> <p>The returned value is <c>true</c> unless <c>info</c> is part of <c>OptionList</c>. </p> - <p><c>erlang:demonitor(MonitorRef, [])</c> is equivalent to - <seealso marker="#demonitor/1">erlang:demonitor(MonitorRef)</seealso>.</p> + <p><c>demonitor(MonitorRef, [])</c> is equivalent to + <seealso marker="#demonitor/1">demonitor(MonitorRef)</seealso>.</p> <p>Currently the following <c>Option</c>s are valid:</p> <taglist> <tag><c>flush</c></tag> @@ -821,11 +821,11 @@ false</pre> <p>Remove (one) <c>{_, MonitorRef, _, _, _}</c> message, if there is one, from the callers message queue after monitoring has been stopped.</p> - <p>Calling <c>erlang:demonitor(MonitorRef, [flush])</c> + <p>Calling <c>demonitor(MonitorRef, [flush])</c> is equivalent to the following, but more efficient:</p> <code type="none"> - erlang:demonitor(MonitorRef), + demonitor(MonitorRef), receive {_, MonitorRef, _, _, _} -> true @@ -863,7 +863,7 @@ false</pre> </note> <p>Failure: <c>badarg</c> if <c>OptionList</c> is not a list, or if <c>Option</c> is not a valid option, or the same failure as for - <seealso marker="#demonitor/1">erlang:demonitor/1</seealso></p> + <seealso marker="#demonitor/1">demonitor/1</seealso></p> </desc> </func> <func> @@ -944,7 +944,7 @@ b</pre> </desc> </func> <func> - <name>erlang:error(Reason)</name> + <name>error(Reason)</name> <fsummary>Stop execution with a given reason</fsummary> <type> <v>Reason = term()</v> @@ -957,7 +957,7 @@ b</pre> function first). Since evaluating this function causes the process to terminate, it has no return value.</p> <pre> -> <input>catch erlang:error(foobar).</input> +> <input>catch error(foobar).</input> {'EXIT',{foobar,[{erl_eval,do_apply,5}, {erl_eval,expr,5}, {shell,exprs,6}, @@ -966,7 +966,7 @@ b</pre> </desc> </func> <func> - <name>erlang:error(Reason, Args)</name> + <name>error(Reason, Args)</name> <fsummary>Stop execution with a given reason</fsummary> <type> <v>Reason = term()</v> @@ -1483,7 +1483,7 @@ os_prompt%</pre> </desc> </func> <func> - <name>erlang:integer_to_list(Integer, Base) -> string()</name> + <name>integer_to_list(Integer, Base) -> string()</name> <fsummary>Text representation of an integer</fsummary> <type> <v>Integer = int()</v> @@ -1493,7 +1493,7 @@ os_prompt%</pre> <p>Returns a string which corresponds to the text representation of <c>Integer</c> in base <c>Base</c>.</p> <pre> -> <input>erlang:integer_to_list(1023, 16).</input> +> <input>integer_to_list(1023, 16).</input> "3FF"</pre> </desc> </func> @@ -1932,7 +1932,7 @@ os_prompt%</pre> </desc> </func> <func> - <name>erlang:list_to_integer(String, Base) -> int()</name> + <name>list_to_integer(String, Base) -> int()</name> <fsummary>Convert from text representation to an integer</fsummary> <type> <v>String = string()</v> @@ -1942,7 +1942,7 @@ os_prompt%</pre> <p>Returns an integer whose text representation in base <c>Base</c> is <c>String</c>.</p> <pre> -> <input>erlang:list_to_integer("3FF", 16).</input> +> <input>list_to_integer("3FF", 16).</input> 1023</pre> <p>Failure: <c>badarg</c> if <c>String</c> contains a bad representation of an integer.</p> @@ -2034,16 +2034,18 @@ os_prompt%</pre> <v>Text = string()</v> </type> <desc> - <warning> - <p>This BIF is still an experimental feature. The interface - may be changed in any way in future releases.</p><p>In - R13B03 the return value on failure was + <note> + <p>In releases older than OTP R14B, NIFs were an + experimental feature. Versions of OTP older than R14B might + have different and possibly incompatible NIF semantics and + interfaces. For example, in R13B03 the return value on + failure was <c>{error,Reason,Text}</c>.</p> - </warning> + </note> <p>Loads and links a dynamic library containing native implemented functions (NIFs) for a module. <c>Path</c> is a file path to the sharable object/dynamic library file minus - the OS-dependant file extension (.so for Unix and .ddl for + the OS-dependent file extension (.so for Unix and .dll for Windows). See <seealso marker="erl_nif">erl_nif</seealso> on how to implement a NIF library.</p> <p><c>LoadInfo</c> can be any term. It will be passed on to @@ -2160,7 +2162,7 @@ os_prompt%</pre> </desc> </func> <func> - <name>make_ref() -> ref()</name> + <name>make_ref() -> reference()</name> <fsummary>Return an almost unique reference</fsummary> <desc> <p>Returns an almost unique reference.</p> @@ -2209,7 +2211,7 @@ os_prompt%</pre> </desc> </func> <func> - <name>erlang:max(Term1, Term2) -> Maximum</name> + <name>max(Term1, Term2) -> Maximum</name> <fsummary>Return the largest of two term</fsummary> <type> <v>Term1 = Term2 = Maximum = term()</v> @@ -2458,7 +2460,7 @@ os_prompt%</pre> </desc> </func> <func> - <name>erlang:min(Term1, Term2) -> Minimum</name> + <name>min(Term1, Term2) -> Minimum</name> <fsummary>Return the smallest of two term</fsummary> <type> <v>Term1 = Term2 = Minimum = term()</v> @@ -2486,7 +2488,7 @@ os_prompt%</pre> </desc> </func> <func> - <name>erlang:monitor(Type, Item) -> MonitorRef</name> + <name>monitor(Type, Item) -> MonitorRef</name> <fsummary>Start monitoring</fsummary> <type> <v>Type = process</v> @@ -2522,7 +2524,7 @@ os_prompt%</pre> <note> <p>When a process is monitored by registered name, the process that has the registered name at the time when - <c>erlang:monitor/2</c> is called will be monitored. + <c>monitor/2</c> is called will be monitored. The monitor will not be effected, if the registered name is unregistered.</p> </note> @@ -2556,20 +2558,20 @@ os_prompt%</pre> </item> </taglist> <note> - <p>If/when <c>erlang:monitor/2</c> is extended (e.g. to + <p>If/when <c>monitor/2</c> is extended (e.g. to handle other item types than <c>process</c>), other possible values for <c>Object</c>, and <c>Info</c> in the <c>'DOWN'</c> message will be introduced.</p> </note> <p>The monitoring is turned off either when the <c>'DOWN'</c> message is sent, or when - <seealso marker="#demonitor/1">erlang:demonitor/1</seealso> + <seealso marker="#demonitor/1">demonitor/1</seealso> is called.</p> <p>If an attempt is made to monitor a process on an older node (where remote process monitoring is not implemented or one where remote process monitoring by registered name is not implemented), the call fails with <c>badarg</c>.</p> - <p>Making several calls to <c>erlang:monitor/2</c> for the same + <p>Making several calls to <c>monitor/2</c> for the same <c>Item</c> is not an error; it results in as many, completely independent, monitorings.</p> <note> @@ -2644,6 +2646,37 @@ os_prompt%</pre> </desc> </func> <func> + <name>erlang:nif_error(Reason)</name> + <fsummary>Stop execution with a given reason</fsummary> + <type> + <v>Reason = term()</v> + </type> + <desc> + <p>Works exactly like + <seealso marker="#error/1">erlang:error/1</seealso>, + but Dialyzer thinks that this BIF will return an arbitrary term. + When used in a stub function for a NIF to generate an + exception when the NIF library is not loaded, Dialyzer + will not generate false warnings.</p> + </desc> + </func> + <func> + <name>erlang:nif_error(Reason, Args)</name> + <fsummary>Stop execution with a given reason</fsummary> + <type> + <v>Reason = term()</v> + <v>Args = [term()]</v> + </type> + <desc> + <p>Works exactly like + <seealso marker="#error/2">erlang:error/2</seealso>, + but Dialyzer thinks that this BIF will return an arbitrary term. + When used in a stub function for a NIF to generate an + exception when the NIF library is not loaded, Dialyzer + will not generate false warnings.</p> + </desc> + </func> + <func> <name>node() -> Node</name> <fsummary>Name of the local node</fsummary> <type> @@ -2659,7 +2692,7 @@ os_prompt%</pre> <name>node(Arg) -> Node</name> <fsummary>At which node is a pid, port or reference located</fsummary> <type> - <v>Arg = pid() | port() | ref()</v> + <v>Arg = pid() | port() | reference()</v> <v>Node = node()</v> </type> <desc> @@ -2736,8 +2769,10 @@ os_prompt%</pre> Otherwise, some other point in time is chosen. It is also guaranteed that subsequent calls to this BIF returns continuously increasing values. Hence, the return value from - <c>now()</c> can be used to generate unique time-stamps. It - can only be used to check the local time of day if + <c>now()</c> can be used to generate unique time-stamps, + and if it is called in a tight loop on a fast machine + the time of the node can become skewed.</p> + <p>It can only be used to check the local time of day if the time-zone info of the underlying operating system is properly configured.</p> </desc> @@ -2746,14 +2781,17 @@ os_prompt%</pre> <name>open_port(PortName, PortSettings) -> port()</name> <fsummary>Open a port</fsummary> <type> - <v>PortName = {spawn, Command} | {spawn_driver, Command} | {spawn_executable, Command} | {fd, In, Out}</v> + <v>PortName = {spawn, Command} | {spawn_driver, Command} | {spawn_executable, FileName} | {fd, In, Out}</v> <v> Command = string()</v> + <v> FileName = [ FileNameChar ] | binary()</v> + <v> FileNameChar = int() (1..255 or any Unicode codepoint, see description)</v> <v> In = Out = int()</v> <v>PortSettings = [Opt]</v> - <v> Opt = {packet, N} | stream | {line, L} | {cd, Dir} | {env, Env} | {args, [ string() ]} | {arg0, string()} | exit_status | use_stdio | nouse_stdio | stderr_to_stdout | in | out | binary | eof</v> + <v> Opt = {packet, N} | stream | {line, L} | {cd, Dir} | {env, Env} | {args, [ ArgString ]} | {arg0, ArgString} | exit_status | use_stdio | nouse_stdio | stderr_to_stdout | in | out | binary | eof</v> <v> N = 1 | 2 | 4</v> <v> L = int()</v> <v> Dir = string()</v> + <v> ArgString = [ FileNameChar ] | binary()</v> <v> Env = [{Name, Val}]</v> <v> Name = string()</v> <v> Val = string() | false</v> @@ -2816,7 +2854,26 @@ os_prompt%</pre> executed, the appropriate command interpreter will implicitly be invoked, but there will still be no command argument expansion or implicit PATH search.</p> - + + <p>The name of the executable as well as the arguments + given in <c>args</c> and <c>arg0</c> is subject to + Unicode file name translation if the system is running + in Unicode file name mode. To avoid + translation or force i.e. UTF-8, supply the executable + and/or arguments as a binary in the correct + encoding. See the <seealso + marker="kernel:file">file</seealso> module, the + <seealso marker="kernel:file#native_name_encoding/0"> + file:native_name_encoding/0</seealso> function and the + <seealso marker="stdlib:unicode_usage">stdlib users guide + </seealso> for details.</p> + + <note>The characters in the name (if given as a list) + can only be > 255 if the Erlang VM is started in + Unicode file name translation mode, otherwise the name + of the executable is limited to the ISO-latin-1 + character set.</note> + <p>If the <c>Command</c> cannot be run, an error exception, with the posix error code as the reason, is raised. The error reason may differ between operating @@ -2919,6 +2976,21 @@ os_prompt%</pre> should not be given in this list. The proper executable name will automatically be used as argv[0] where applicable.</p> + <p>When the Erlang VM is running in Unicode file name + mode, the arguments can contain any Unicode characters and + will be translated into whatever is appropriate on the + underlying OS, which means UTF-8 for all platforms except + Windows, which has other (more transparent) ways of + dealing with Unicode arguments to programs. To avoid + Unicode translation of arguments, they can be supplied as + binaries in whatever encoding is deemed appropriate.</p> + + <note>The characters in the arguments (if given as a + list of characters) can only be > 255 if the Erlang + VM is started in Unicode file name mode, + otherwise the arguments are limited to the + ISO-latin-1 character set.</note> + <p>If one, for any reason, wants to explicitly set the program name in the argument vector, the <c>arg0</c> option can be used.</p> @@ -2934,6 +3006,9 @@ os_prompt%</pre> responds to this is highly system dependent and no specific effect is guaranteed.</p> + <p>The unicode file name translation rules of the + <c>args</c> option apply to this option as well.</p> + </item> <tag><c>exit_status</c></tag> @@ -3200,7 +3275,7 @@ os_prompt%</pre> </desc> </func> <func> - <name>erlang:port_command(Port, Data, OptionList) -> true|false</name> + <name>port_command(Port, Data, OptionList) -> true|false</name> <fsummary>Send data to a port</fsummary> <type> <v>Port = port() | atom()</v> @@ -3236,10 +3311,6 @@ os_prompt%</pre> <note> <p>More options may be added in the future.</p> </note> - <note> - <p><c>erlang:port_command/3</c> is currently not auto imported, but - it is planned to be auto imported in OTP R14.</p> - </note> <p>Failures:</p> <taglist> <tag><c>badarg</c></tag> @@ -3868,11 +3939,11 @@ os_prompt%</pre> <tag><c>{monitored_by, Pids}</c></tag> <item> <p>A list of pids that are monitoring the process (with - <c>erlang:monitor/2</c>).</p> + <c>monitor/2</c>).</p> </item> <tag><c>{monitors, Monitors}</c></tag> <item> - <p>A list of monitors (started by <c>erlang:monitor/2</c>) + <p>A list of monitors (started by <c>monitor/2</c>) that are active for the process. For a local process monitor or a remote process monitor by pid, the list item is <c>{process, Pid}</c>, and for a remote process @@ -3909,7 +3980,8 @@ os_prompt%</pre> <tag><c>{status, Status}</c></tag> <item> <p><c>Status</c> is the status of the process. <c>Status</c> - is <c>waiting</c> (waiting for a message), <c>running</c>, + is <c>exiting</c>, <c>garbage_collecting</c>, + <c>waiting</c> (for a message), <c>running</c>, <c>runnable</c> (ready to run, but another process is running), or <c>suspended</c> (suspended on a "busy" port or by the <c>erlang:suspend_process/[1,2]</c> BIF).</p> @@ -4061,7 +4133,7 @@ os_prompt%</pre> terminate, it has no return value - unless the arguments are invalid, in which case the function <em>returns the error reason</em>, that is <c>badarg</c>. If you want to be really sure not to return you can call - <c>erlang:error(erlang:raise(Class, Reason, Stacktrace))</c> + <c>error(erlang:raise(Class, Reason, Stacktrace))</c> and hope to distinguish exceptions later.</p> </desc> </func> @@ -4069,7 +4141,7 @@ os_prompt%</pre> <name>erlang:read_timer(TimerRef) -> int() | false</name> <fsummary>Number of milliseconds remaining for a timer</fsummary> <type> - <v>TimerRef = ref()</v> + <v>TimerRef = reference()</v> </type> <desc> <p><c>TimerRef</c> is a timer reference returned by @@ -4092,7 +4164,7 @@ os_prompt%</pre> <name>erlang:ref_to_list(Ref) -> string()</name> <fsummary>Text representation of a reference</fsummary> <type> - <v>Ref = ref()</v> + <v>Ref = reference()</v> </type> <desc> <p>Returns a string which corresponds to the text @@ -4271,7 +4343,7 @@ true</pre> <v>Dest = pid() | RegName </v> <v> LocalPid = pid() (of a process, alive or dead, on the local node)</v> <v>Msg = term()</v> - <v>TimerRef = ref()</v> + <v>TimerRef = reference()</v> </type> <desc> <p>Starts a timer which will send the message <c>Msg</c> @@ -4484,7 +4556,7 @@ true</pre> </desc> </func> <func> - <name>spawn(Node, Module, Function, ArgumentList) -> pid()</name> + <name>spawn(Node, Module, Function, Args) -> pid()</name> <fsummary>Create a new process with a function as entry point on a given node</fsummary> <type> <v>Node = node()</v> @@ -4662,7 +4734,7 @@ true</pre> <tag><c>monitor</c></tag> <item> <p>Monitor the new process (just like - <seealso marker="#monitor/2">erlang:monitor/2</seealso> does).</p> + <seealso marker="#monitor/2">monitor/2</seealso> does).</p> </item> <tag><c>{priority, Level}</c></tag> <item> @@ -4800,7 +4872,7 @@ true</pre> <v> LocalPid = pid() (of a process, alive or dead, on the local node)</v> <v> RegName = atom()</v> <v>Msg = term()</v> - <v>TimerRef = ref()</v> + <v>TimerRef = reference()</v> </type> <desc> <p>Starts a timer which will send the message @@ -5146,9 +5218,9 @@ true</pre> schedulers actually have bound as requested, call <seealso marker="#system_info_scheduler_bindings">erlang:system_info(scheduler_bindings)</seealso>. </p> - <p>Schedulers can currently only be bound on newer Linux - and Solaris systems, but more systems will be supported - in the future. + <p>Schedulers can currently only be bound on newer Linux, + Solaris, FreeBSD, and Windows systems, but more systems will be + supported in the future. </p> <p>In order for the runtime system to be able to bind schedulers, the CPU topology needs to be known. If the runtime system fails @@ -5335,7 +5407,7 @@ true</pre> <p>Returns <c>{Allocator, Version, Features, Settings}.</c></p> <p>Types:</p> <list type="bulleted"> - <item><c>Allocator = undefined | elib_malloc | glibc</c></item> + <item><c>Allocator = undefined | glibc</c></item> <item><c>Version = [int()]</c></item> <item><c>Features = [atom()]</c></item> <item><c>Settings = [{Subsystem, [{Parameter, Value}]}]</c></item> @@ -5350,7 +5422,7 @@ true</pre> implementation used. If <c>Allocator</c> equals <c>undefined</c>, the <c>malloc()</c> implementation used could not be identified. Currently - <c>elib_malloc</c> and <c>glibc</c> can be identified.</p> + <c>glibc</c> can be identified.</p> </item> <item> <p><c>Version</c> is a list of integers (but not a @@ -5427,6 +5499,16 @@ true</pre> <seealso marker="#system_info_allocator_tuple">erlang:system_info({allocator, Alloc})</seealso>. </p> </item> + <tag><c>build_type</c></tag> + <item> + <p>Returns an atom describing the build type of the runtime + system. This is normally the atom <c>opt</c> for optimized. + Other possible return values are <c>debug</c>, <c>purify</c>, + <c>quantify</c>, <c>purecov</c>, <c>gcov</c>, <c>valgrind</c>, + <c>gprof</c>, and <c>lcnt</c>. Possible return values + may be added and/or removed at any time without prior notice. + </p> + </item> <tag><c>c_compiler_used</c></tag> <item> <p>Returns a two-tuple describing the C compiler used when @@ -5504,7 +5586,7 @@ true</pre> <c>CpuTopology</c> type to change. </p> </item> - <tag><c>{cpu_topology, defined}</c></tag> + <tag><marker id="system_info_cpu_topology_defined"><c>{cpu_topology, defined}</c></marker></tag> <item> <p>Returns the user defined <c>CpuTopology</c>. For more information see the documentation of @@ -5514,12 +5596,14 @@ true</pre> argument. </p> </item> - <tag><c>{cpu_topology, detected}</c></tag> + <tag><marker id="system_info_cpu_topology_detected"><c>{cpu_topology, detected}</c></marker></tag> <item> <p>Returns the automatically detected <c>CpuTopology</c>. The emulator currently only detects the CPU topology on some newer - linux and solaris systems. For more information see the - documentation of the + Linux, Solaris, FreeBSD, and Windows systems. On Windows system with + more than 32 logical processors the CPU topology is not detected. + </p> + <p>For more information see the documentation of the <seealso marker="#system_info_cpu_topology">cpu_topology</seealso> argument. </p> @@ -5577,52 +5661,16 @@ true</pre> </item> <tag><c>elib_malloc</c></tag> <item> - <p>If the emulator uses the <c>elib_malloc</c> memory - allocator, a list of two-element tuples containing status - information is returned; otherwise, <c>false</c> is - returned. The list currently contains the following - two-element tuples (all sizes are presented in bytes):</p> - <taglist> - <tag><c>{heap_size, Size}</c></tag> - <item> - <p>Where <c>Size</c> is the current heap size.</p> - </item> - <tag><c>{max_alloced_size, Size}</c></tag> - <item> - <p>Where <c>Size</c> is the maximum amount of memory - allocated on the heap since the emulator started.</p> - </item> - <tag><c>{alloced_size, Size}</c></tag> - <item> - <p>Where <c>Size</c> is the current amount of memory - allocated on the heap.</p> - </item> - <tag><c>{free_size, Size}</c></tag> - <item> - <p>Where <c>Size</c> is the current amount of free - memory on the heap.</p> - </item> - <tag><c>{no_alloced_blocks, No}</c></tag> - <item> - <p>Where <c>No</c> is the current number of allocated - blocks on the heap.</p> - </item> - <tag><c>{no_free_blocks, No}</c></tag> - <item> - <p>Where <c>No</c> is the current number of free blocks - on the heap.</p> - </item> - <tag><c>{smallest_alloced_block, Size}</c></tag> - <item> - <p>Where <c>Size</c> is the size of the smallest - allocated block on the heap.</p> - </item> - <tag><c>{largest_free_block, Size}</c></tag> - <item> - <p>Where <c>Size</c> is the size of the largest free - block on the heap.</p> - </item> - </taglist> + <p>This option will be removed in a future release. + The return value will always be <c>false</c> since + the elib_malloc allocator has been removed.</p> + </item> + <tag><marker id="system_info_dist_buf_busy_limit"><c>dist_buf_busy_limit</c></marker></tag> + <item> + <p>Returns the value of the distribution buffer busy limit + in bytes. This limit can be set on startup by passing the + <seealso marker="erl#+zdbbl">+zdbbl</seealso> command line + flag to <c>erl</c>.</p> </item> <tag><c>fullsweep_after</c></tag> <item> @@ -5698,11 +5746,34 @@ true</pre> information see the <seealso marker="erts:crash_dump">"How to interpret the Erlang crash dumps"</seealso> chapter in the ERTS User's Guide.</p> </item> - <tag><c>logical_processors</c></tag> + <tag><marker id="logical_processors"><c>logical_processors</c></marker></tag> <item> - <p>Returns the number of logical processors detected on the - system as an integer or the atom <c>unknown</c> if the - emulator wasn't able to detect any. + <p>Returns the detected number of logical processors configured + on the system. The return value is either an integer, or + the atom <c>unknown</c> if the emulator wasn't able to + detect logical processors configured. + </p> + </item> + <tag><marker id="logical_processors_available"><c>logical_processors_available</c></marker></tag> + <item> + <p>Returns the detected number of logical processors available to + the Erlang runtime system. The return value is either an + integer, or the atom <c>unknown</c> if the emulator wasn't + able to detect logical processors available. The number + of logical processors available is less than or equal to + the number of <seealso marker="#logical_processors_online">logical + processors online</seealso>. + </p> + </item> + <tag><marker id="logical_processors_online"><c>logical_processors_online</c></marker></tag> + <item> + <p>Returns the detected number of logical processors online on + the system. The return value is either an integer, + or the atom <c>unknown</c> if the emulator wasn't able to + detect logical processors online. The number of logical + processors online is less than or equal to the number of + <seealso marker="#logical_processors">logical processors + configured</seealso>. </p> </item> <tag><c>machine</c></tag> @@ -5907,6 +5978,26 @@ true</pre> <c>get_tcw</c> in "Match Specifications in Erlang", <seealso marker="erts:match_spec#get_tcw">ERTS User's Guide</seealso>.</p> </item> + <tag><marker id="update_cpu_info"><c>update_cpu_info</c></marker></tag> + <item> + <p>The runtime system rereads the CPU information available and + updates its internally stored information about the + <seealso marker="#system_info_cpu_topology_detected">detected CPU + topology</seealso> and the amount of logical processors + <seealso marker="#logical_processors">configured</seealso>, + <seealso marker="#logical_processors_online">online</seealso>, and + <seealso marker="#logical_processors_available">available</seealso>. + If the CPU information has changed since the last time it was read, + the atom <c>changed</c> is returned; otherwise, the atom + <c>unchanged</c> is returned. If the CPU information has changed + you probably want to + <seealso marker="#system_flag_schedulers_online">adjust the amount + of schedulers online</seealso>. You typically want to have as + many schedulers online as + <seealso marker="#logical_processors_available">logical processors + available</seealso>. + </p> + </item> <tag><marker id="system_info_version"><c>version</c></marker></tag> <item> <p>Returns a string containing the version number of the diff --git a/erts/doc/src/erlc.xml b/erts/doc/src/erlc.xml index 1e8960c22c..ebf76a2afe 100644 --- a/erts/doc/src/erlc.xml +++ b/erts/doc/src/erlc.xml @@ -4,7 +4,7 @@ <comref> <header> <copyright> - <year>1997</year><year>2010</year> + <year>1997</year><year>2011</year> <holder>Ericsson AB. All Rights Reserved.</holder> </copyright> <legalnotice> @@ -141,6 +141,50 @@ for compiling native code, which needs to be compiled with the same run-time system that it should be run on.</p> </item> + <tag>-M</tag> + <item> + <p>Produces a Makefile rule to track headers dependencies. The + rule is sent to stdout. No object file is produced. + </p> + </item> + <tag>-MF <em>Makefile</em></tag> + <item> + <p>Like the <c><![CDATA[-M]]></c> option above, except that the + Makefile is written to <em>Makefile</em>. No object + file is produced. + </p> + </item> + <tag>-MD</tag> + <item> + <p>Same as <c><![CDATA[-M -MF <File>.Pbeam]]></c>. + </p> + </item> + <tag>-MT <em>Target</em></tag> + <item> + <p>In conjunction with <c><![CDATA[-M]]></c> or + <c><![CDATA[-MF]]></c>, change the name of the rule emitted + to <em>Target</em>. + </p> + </item> + <tag>-MQ <em>Target</em></tag> + <item> + <p>Like the <c><![CDATA[-MT]]></c> option above, except that + characters special to make(1) are quoted. + </p> + </item> + <tag>-MP</tag> + <item> + <p>In conjunction with <c><![CDATA[-M]]></c> or + <c><![CDATA[-MF]]></c>, add a phony target for each dependency. + </p> + </item> + <tag>-MG</tag> + <item> + <p>In conjunction with <c><![CDATA[-M]]></c> or + <c><![CDATA[-MF]]></c>, consider missing headers as generated + files and add them to the dependencies. + </p> + </item> <tag>--</tag> <item> <p>Signals that no more options will follow. diff --git a/erts/doc/src/escript.xml b/erts/doc/src/escript.xml index 44c9a5ac68..588508aae6 100644 --- a/erts/doc/src/escript.xml +++ b/erts/doc/src/escript.xml @@ -153,7 +153,10 @@ halt(1).</pre> <p>Execution of interpreted code is slower than compiled code. If much of the execution takes place in interpreted code it may be worthwhile to compile it, even though the compilation - itself will take a little while.</p> + itself will take a little while. It is also possible to supply + <c>native</c> instead of compile, this will compile the script + using the native flag, again depending on the characteristics + of the escript this could or could not be worth while.</p> <p>As mentioned earlier, it is possible to have a script which contains precompiled <c>beam</c> code. In a precompiled @@ -397,6 +400,9 @@ ok Warnings and errors (if any) are written to the standard output, but the script will not be run. The exit status will be 0 if there were no errors, and 127 otherwise.</item> + + <tag>-n</tag> + <item>Compile the escript using the +native flag.</item> </taglist> </section> </comref> diff --git a/erts/doc/src/notes.xml b/erts/doc/src/notes.xml index a4867adf22..77181d3407 100644 --- a/erts/doc/src/notes.xml +++ b/erts/doc/src/notes.xml @@ -30,6 +30,1320 @@ </header> <p>This document describes the changes made to the ERTS application.</p> +<section><title>Erts 5.8.2</title> + + <section><title>Fixed Bugs and Malfunctions</title> + <list> + <item> + <p> Fix format_man_pages so it handles all man sections + and remove warnings/errors in various man pages. </p> + <p> + Own Id: OTP-8600</p> + </item> + <item> + <p> + The <c>configure</c> command line argument <seealso + marker="doc/installation_guide:INSTALL#How-to-Build-and-Install-ErlangOTP_A-Closer-Look-at-the-individual-Steps_Configuring">--enable-ethread-pre-pentium4-compatibility</seealso> + had no effect. This option is now also automatically + enabled if required on the build machine.</p> + <p> + Own Id: OTP-8847</p> + </item> + <item> + <p> + Windows 2003 and Windows XP pre SP3 would sometimes not + start the Erlang R14B VM at all due to a bug in the cpu + topology detection. The bug affects Windows only, no + other platform is even remotely affected. The bug is now + corrected.</p> + <p> + Own Id: OTP-8876</p> + </item> + <item> + <p> + The HiPE run-time in the 64-bit emulator could do a + 64-bit write to a 32-bit struct field. It happened to be + harmless on Intel/AMD processors. Corrected. (Thanks to + Mikael Pettersson.)</p> + <p> + Own Id: OTP-8877</p> + </item> + <item> + <p> + A bug in <seealso + marker="erl_driver#erl_drv_tsd_get">erl_drv_tsd_get()</seealso> + and <seealso + marker="erl_nif#enif_tsd_get">enif_tsd_get()</seealso> + could cause an emulator crash. These functions are + currently not used in OTP. That is, the crash only occur + on systems with user implemented NIF libraries, or + drivers that use one of these functions.</p> + <p> + Own Id: OTP-8889</p> + </item> + <item> + <p> + Calling <c>erlang:system_info({cpu_topology, + CpuTopologyType})</c> with another <c>CpuTopologyType</c> + element than one of the documented atoms <c>defined</c>, + <c>detected</c>, or <c>used</c> caused an emulator crash. + (Thanks to Paul Guyot)</p> + <p> + Own Id: OTP-8914</p> + </item> + <item> + <p> + The ERTS internal rwlock implementation could get into an + inconsistent state. This bug was very seldom triggered, + but could be during heavy contention. The bug was + introduced in R14B (erts-5.8.1).</p> + <p> + The bug was most likely to be triggered when using the + <c>read_concurrency</c> option on an ETS table that was + frequently accessed from multiple processes doing lots of + writes and reads. That is, in a situation where you + typically don't want to use the <c>read_concurrency</c> + option in the first place.</p> + <p> + Own Id: OTP-8925 Aux Id: OTP-8544 </p> + </item> + <item> + <p> + Tracing to port could cause an emulator crash when + unloading the trace driver.</p> + <p> + Own Id: OTP-8932</p> + </item> + <item> + <p> + Removed use of CancelIoEx on Windows that had been shown + to cause problems with some drivers.</p> + <p> + Own Id: OTP-8937</p> + </item> + <item> + <p> + The fallback implementation used when no native atomic + implementation was found did not compile. (Thanks to + Patrick Baggett, and Tuncer Ayaz)</p> + <p> + Own Id: OTP-8944</p> + </item> + <item> + <p> + Some integer values used during load balancing could + under rare circumstances wrap causing a load unbalance + between schedulers.</p> + <p> + Own Id: OTP-8950</p> + </item> + <item> + <p> + The windows VM now correctly handles appending to large + files (> 4GB).</p> + <p> + Own Id: OTP-8958</p> + </item> + <item> + <p> + Name resolving of IPv6 addresses has been implemented for + Windows versions that support it. The use of ancient + resolver flags (AI_V4MAPPED | AI_ADDRCONFIG) to the + getaddrinfo() function has been removed since e.g FreeBSD + regard mapped IPv4 addresses to be a security problem and + the semantics of the address configured flag is + uncertain.</p> + <p> + Own Id: OTP-8969</p> + </item> + </list> + </section> + + + <section><title>Improvements and New Features</title> + <list> + <item> + <p> + The help texts produced by the <c>configure</c> scripts + in the top directory and in the erts directory have been + aligned and cleaned up.</p> + <p> + Own Id: OTP-8859</p> + </item> + <item> + <p> + When the runtime system had fewer schedulers than logical + processors, the system could get an unnecessarily large + amount reader groups.</p> + <p> + Own Id: OTP-8861</p> + </item> + <item> + <p> + <c>run_rel</c> has been updated to support Solaris's + /dev/ptmx device and to load the necessary STREAMS + modules so that <c>to_erl</c> can provide terminal echo + of keyboard input. (Thanks to Ryan Tilder.)</p> + <p> + Own Id: OTP-8878</p> + </item> + <item> + <p> + The Erlang VM now supports Unicode filenames. The feature + is turned on by default on systems where Unicode + filenames are mandatory (Windows and MacOSX), but can be + enabled on other systems with the '+fnu' emulator option. + Enabling the Unicode filename feature on systems where it + is not default is however considered experimental and not + to be used for production. Together with the Unicode file + name support, the concept of "raw filenames" is + introduced, which means filenames provided without + implicit unicode encoding translation. Raw filenames are + provided as binaries, not lists. For further information, + see stdlib users guide and the chapter about using + Unicode in Erlang. Also see the file module manual page.</p> + <p> + *** POTENTIAL INCOMPATIBILITY ***</p> + <p> + Own Id: OTP-8887</p> + </item> + <item> + <p>Buffer overflows have been prevented in <c>erlc</c>, + <c>dialyzer</c>, <c>typer</c>, <c>run_test</c>, + <c>heart</c>, <c>escript</c>, and <c>erlexec</c>.</p> + (Thanks to Michael Santos.) + <p> + Own Id: OTP-8892</p> + </item> + <item> + <p> + The runtime system is now less eager to suspend processes + sending messages over the distribution. The default value + of the distribution buffer busy limit has also been + increased from 128 KB to 1 MB. This in order to improve + throughput.</p> + <p> + Own Id: OTP-8901</p> + </item> + <item> + <p> + The distribution buffer busy limit can now be configured + at system startup. For more information see the + documentation of the <c>erl</c> <seealso + marker="erl#+zdbbl">+zdbbl</seealso> command line flag. + (Thanks to Scott Lystig Fritchie)</p> + <p> + Own Id: OTP-8912</p> + </item> + <item> + <p> + The inet driver internal buffer stack implementation has + been rewritten in order to reduce lock contention.</p> + <p> + Own Id: OTP-8916</p> + </item> + <item> + <p> + New ETS option <c>compressed</c>, to enable a more + compact storage format at the expence of heavier table + operations. For test and evaluation, <c>erl +ec</c> can + be used to force compression on all ETS tables.</p> + <p> + Own Id: OTP-8922 Aux Id: seq11658 </p> + </item> + <item> + <p> + There is now a new function inet:getifaddrs/0 modeled + after C library function getifaddrs() on BSD and LInux + that reports existing interfaces and their addresses on + the host. This replaces the undocumented and unsupported + inet:getiflist/0 and inet:ifget/2.</p> + <p> + Own Id: OTP-8926</p> + </item> + <item> + <p> + Support for detection of CPU topology and binding of + schedulers on FreeBSD 8 have been added. (Thanks to Paul + Guyot)</p> + <p> + Own Id: OTP-8939</p> + </item> + <item> + <p> + Several bugs related to hibernate/3 and HiPE have been + corrected. (Thanks to Paul Guyot.)</p> + <p> + Own Id: OTP-8952</p> + </item> + <item> + <p> + Support for soft and hard links on Windows versions and + filesystems that support them is added.</p> + <p> + Own Id: OTP-8955</p> + </item> + <item> + <p> + The win32 virtual machine is now linked large address + aware. his allows the Erlang VM to use up to 3 gigs of + address space on Windows instead of the default of 2 + gigs.</p> + <p> + Own Id: OTP-8956</p> + </item> + </list> + </section> + +</section> + +<section><title>Erts 5.8.1.2</title> + + <section><title>Fixed Bugs and Malfunctions</title> + <list> + <item> + <p> Fix that the documentation top index generator can + handle an Ericsson internal application group. </p> + <p> + Own Id: OTP-8875</p> + </item> + <item> + <p>In embedded mode, on_load handlers that called + <c>code:priv_dir/1</c> or other functions in <c>code</c> + would hang the system. Since the <c>crypto</c> + application now contains an on_loader handler that calls + <c>code:priv_dir/1</c>, including the <c>crypto</c> + application in the boot file would prevent the system + from starting.</p> + <p>Also extended the <c>-init_debug</c> option to print + information about on_load handlers being run to + facilitate debugging.</p> + <p> + Own Id: OTP-8902 Aux Id: seq11703 </p> + </item> + </list> + </section> + +</section> + +<section><title>Erts 5.8.1.1</title> + + <section><title>Fixed Bugs and Malfunctions</title> + <list> + <item> + <p> + Windows 2003 and Windows XP pre SP3 would sometimes not + start the Erlang R14B VM at all due to a bug in the cpu + topology detection. The bug affects Windows only, no + other platform is even remotely affected. The bug is now + corrected.</p> + <p> + Own Id: OTP-8876</p> + </item> + </list> + </section> + +</section> + +<section><title>Erts 5.8.1</title> + + <section><title>Fixed Bugs and Malfunctions</title> + <list> + <item> + <p> + Very small floating point numbers generated errors when + converting from list to float in some versions of the VM, + this is now corrected so that i.e. + list_to_float("1.0e-324"). returns 0.0 in all versions of + Erlang.</p> + <p> + Own Id: OTP-7178</p> + </item> + <item> + <p> + Windows Vista and Windows 7 file system virtualization, + which makes "old style" windows programs execute in a + file system sandbox, was previously unintentionally + turned on for the Erlang VM. This is now corrected so + that i.e. writes to C:\Program Files\. without + administrator privileges will fail.</p> + <p> + Own Id: OTP-7405</p> + </item> + <item> + <p> + Fix faulty 64-bit integer term output from drivers. Large + 64-bits integers did not generate correct bignums and + could even cause emulator crash. Only affects drivers + using ERL_DRV_INT64 or ERL_DRV_UINT64, introduced in + R13B03.</p> + <p> + Own Id: OTP-8716</p> + </item> + <item> + <p> + Fixed: inet:setopts(S, [{linger,{true,2}}]) returned + {error,einval} for SCTP sockets. The inet_drv had a bug + when checking the option size.</p> + <p> + Own Id: OTP-8726 Aux Id: seq11617 </p> + </item> + <item> + <p>Fix libm linking with --as-needed flag + <p> + When building with "--as-needed" linker flags on Linux + the build will fail. This has now been fixed.</p> + <p> + (Thanks to Christian Faulhammer)</p></p> + <p> + Own Id: OTP-8728</p> + </item> + <item> + <p> + gen_udp:connect/3 was broken for SCTP enabled builds. It + did not detect remote end errors as it should.</p> + <p> + Own Id: OTP-8729</p> + </item> + <item> + <p>Reduce the risk of integer wrapping in bin vheap size + counting.</p> <p>The vheap size series will now use the + golden ratio instead of doubling and fibonacci + sequences.</p> + <p> + Own Id: OTP-8730</p> + </item> + <item> + <p> + ETS ordered_set containing <c>[]</c> as key could cause + strange thing to happen, like an infinite hanging + <c>ets:select</c>.</p> + <p> + Own Id: OTP-8732</p> + </item> + <item> + <p>reference() has been substituted for ref() in the + documentation.</p> + <p> + Own Id: OTP-8733</p> + </item> + <item> + <p> + When a native compiled module called a not loaded + non-native compiled module that had an on_load function, + the export entries were trashed after code loading so on + the next call from the native compiled module to the + non-native compiled the emulator crashed. This bug has + now been fixed.</p> + <p> + Own Id: OTP-8736</p> + </item> + <item> + <p> + HiPE-enabled Erlang VMs running on BSD systems sometimes + generated messages like "Yikes! erts_alloc() returned + misaligned address 0x8016a512c". Fixed. (Thanks to Mikael + Pettersson.)</p> + <p> + Own Id: OTP-8769</p> + </item> + <item> + <p> + A race condition in <c>erts_poll()</c> could cause delay + of poll for I/O.</p> + <p> + Own Id: OTP-8773</p> + </item> + <item> + <p> + Removed some potential vulnerabilities from the Erlang + Port Mapper Daemon (epmd) and straightened up access + control. Also removed hazardous interfaces allowing + anyone on a machine to forcefully unregister other nodes. + This means that the ei_unregister/erl_unregister + interfaces in erl_interface is rendered not only error + prone and mystifying as before, but totally ineffective. + The old behaviour of unchecked node unregistering can be + restored if needed, see epmd documentation for details.</p> + <p> + *** POTENTIAL INCOMPATIBILITY ***</p> + <p> + Own Id: OTP-8780</p> + </item> + <item> + <p> Building in a source tree without prebuilt platform + independent build results failed on the SSL examples + when: </p> <list><item> cross building. This has been + solved by not building the SSL examples during a cross + build. </item><item> building on Windows. </item></list> + <p> + Own Id: OTP-8791</p> + </item> + <item> + <p> + inet:getsockopt for SCTP sctp_default_send_param had a + bug to not initialize required feilds causing random + answers. It is now corrected.</p> + <p> + Own Id: OTP-8795 Aux Id: seq11655 </p> + </item> + <item> + <p> + The hipe_bifs:get_hrvtime/0 BIF now always returns a real + value even if the "perfctr" Linux kernel extension is not + available. It used to return a dummy value. (Thanks to + Mikael Pettersson.)</p> + <p> + Own Id: OTP-8798</p> + </item> + <item> + <p> + Calling a native-code compiled module with an + <c>on_load</c> function could cause a crash. (Thanks to + Mikael Pettersson.)</p> + <p> + Own Id: OTP-8799</p> + </item> + <item> + <p>The emulator could crash while writing a crash dump if + native-compiled modules had been loaded. (Thanks to Paul + Guyot.)</p> + <p> + Own Id: OTP-8801</p> + </item> + <item> + <p> + The garbage collector could crash if invoked from + native-compiled code after a call to a BIF. (Thanks to + Paul Guyot.)</p> + <p> + Own Id: OTP-8821</p> + </item> + <item> + <p> + A rare memory leak in binary:matches is removed</p> + <p> + Own Id: OTP-8823</p> + </item> + <item> + <p>For a socket in the HTTP packet mode, the return value + from <c>gen_tcp:recv/2,3</c> if there is an error in the + header will be <c>{ok,{http_error,String}}</c> instead of + <c>{error,{http_error,String}}</c> to be consistent with + <c>ssl:recv/2,3</c>.</p> + <p> + *** POTENTIAL INCOMPATIBILITY ***</p> + <p> + Own Id: OTP-8831</p> + </item> + </list> + </section> + + + <section><title>Improvements and New Features</title> + <list> + <item> + <p> + ets:select_reverse/{1,2,3} are now documented.</p> + <p> + Own Id: OTP-7863</p> + </item> + <item> + <p> + External format of integers changed to make full use of + all 32 bits of INTEGER_EXT. This is a compatible change + as old code can read full 32-bit integers but only + produce 28-bit integers as INTEGER_EXT.</p> + <p> + Own Id: OTP-8540 Aux Id: seq11534 </p> + </item> + <item> + <p> + Large parts of the <c>ethread</c> library have been + rewritten. The <c>ethread</c> library is an Erlang + runtime system internal, portable thread library used by + the runtime system itself.</p> + <p> + Most notable improvement is a reader optimized rwlock + implementation which dramatically improve the performance + of read-lock/read-unlock operations on multi processor + systems by avoiding ping-ponging of the rwlock cache + lines. The reader optimized rwlock implementation is used + by miscellaneous rwlocks in the runtime system that are + known to be read-locked frequently, and can be enabled on + ETS tables by passing the <seealso + marker="stdlib:ets#new_2_read_concurrency">{read_concurrency, + true}</seealso> option upon table creation. See the + documentation of <seealso + marker="stdlib:ets#new/2">ets:new/2</seealso> for more + information. The reader optimized rwlock implementation + can be fine tuned when starting the runtime system. For + more information, see the documentation of the <seealso + marker="erts:erl#+rg">+rg</seealso> command line argument + of <c>erl</c>.</p> + <p> + There is also a new implementation of rwlocks that is not + optimized for readers. Both implementations interleaves + readers and writers during contention as opposed to, + e.g., the NPTL (Linux) pthread rwlock implementation + which use either a reader or writer preferred strategy. + The reader/writer preferred strategy is problematic since + it starves threads doing the non-preferred operation.</p> + <p> + The new rwlock implementations in general performs better + in ERTS than common pthread implementations. However, in + some extremely heavily contended cases this is not the + case. Such heavy contention can more or less only appear + on ETS tables. This when multiple processes do very large + amounts of write locked operations simultaneously on the + same table. Such use of ETS is bad regardless of rwlock + implementation, will never scale, and is something we + strongly advise against.</p> + <p> + The new rwlock implementations depend on atomic + operations. If no native atomic implementation is found, + a fallback solution will be used. Using the fallback + implies a performance degradation. That is, it is more + important now than before to build OTP with a native + atomic implementation.</p> + <p> + The <c>ethread</c> library contains native atomic + implementations for, x86 (32 and 64 bit), powerpc (32 + bit), sparc V9 (32 and 64 bit), and tilera (32 bit). On + other hardware gcc's builtin support for atomic memory + access will be used if such exists. If no such support is + found, <c>configure</c> will warn about no atomic + implementation available.</p> + <p> + The <c>ethread</c> library can now also use the + <c>libatomic_ops</c> library for atomic memory accesses. + This makes it possible for the Erlang runtime system to + utilize optimized native atomic operations on more + platforms than before. If <c>configure</c> warns about no + atomic implementation available, try using the + <c>libatomic_ops</c> library. Use the <seealso + marker="doc/installation_guide:INSTALL#How-to-Build-and-Install-ErlangOTP_A-Closer-Look-at-the-individual-Steps_Configuring">--with-libatomic_ops=PATH</seealso> + <c>configure</c> command line argument when specifying + where the <c>libatomic_ops</c> installation is located. + The <c>libatomic_ops</c> library can be downloaded from: + <url + href="http://www.hpl.hp.com/research/linux/atomic_ops/">http://www.hpl.hp.com/research/linux/atomic_ops/</url></p> + <p> + The changed API of the <c>ethread</c> library has also + caused modifications in the Erlang runtime system. + Preparations for the to come "delayed deallocation" + feature has also been done since it depends on the + <c>ethread</c> library.</p> + <p> + <em>Note</em>: When building for x86, the <c>ethread</c> + library will now use instructions that first appeared on + the pentium 4 processor. If you want the runtime system + to be compatible with older processors (back to 486) you + need to pass the <seealso + marker="doc/installation_guide:INSTALL#How-to-Build-and-Install-ErlangOTP_A-Closer-Look-at-the-individual-Steps_Configuring">--enable-ethread-pre-pentium4-compatibility</seealso> + <c>configure</c> command line argument when configuring + the system.</p> + <p> + Own Id: OTP-8544</p> + </item> + <item> + <p> + erlang:localtime_to_universaltime({{2008, 8, 1}, {0, 0, + 0}},true) when TZ=UTC now behaves consistently on all + Unix platforms.</p> + <p> + The problem fixed was originally reported by Paul Guyot + on erlang-bugs mailing list:</p> + <p> + http://www.erlang.org/pipermail/erlang-bugs/2008-November/001077.html</p> + <p> + Own Id: OTP-8580</p> + </item> + <item> + <p> + Optimization reducing memory consumption by two words per + ETS object.</p> + <p> + Own Id: OTP-8737</p> + </item> + <item> + <p> + Fixes for unsupported halfword-emulator</p> + <p> + Own Id: OTP-8745</p> + </item> + <item> + <p> + NIF 64-bit integer support; <c>enif_get_int64</c>, + <c>enif_get_uint64</c>, <c>enif_make_int64</c>, + <c>enif_make_uint64</c>.</p> + <p> + Own Id: OTP-8746</p> + </item> + <item> + <p> + Alignment of trailing data in messages has been adjusted. + This in order to be able to pass data of any type as + trailing data in the future.</p> + <p> + Own Id: OTP-8754</p> + </item> + <item> + <p> + The obsolete/driver.h header file has been removed. It + has been obsolete and deprecated since R8B. Drivers that + still include obsolete/driver.h must be updated to + include erl_driver.h.</p> + <p> + *** POTENTIAL INCOMPATIBILITY ***</p> + <p> + Own Id: OTP-8758</p> + </item> + <item> + <p> + Added erlang:system_info(build_type) which makes it + easier to chose drivers, NIF libraries, etc based on + build type of the runtime system.</p> + <p> + The NIF library for crypto can now be built for valgrind + and/or debug as separate NIF libraries that will be + automatically loaded if the runtime system has been built + with a matching build type.</p> + <p> + Own Id: OTP-8760</p> + </item> + <item> + <p> + Further lessened the memory requirements of ETS objects.</p> + <p> + Own Id: OTP-8762</p> + </item> + <item> + <p>The broken elib_malloc alternate memory allocator has + been removed. <c>erlang:system_info(elib_malloc)</c> will + always return <c>false</c>, and in R15, + <c>erlang:system_info(elib_malloc)</c> will fail with a + <c>badarg</c> exception.</p> + <p> + Own Id: OTP-8764</p> + </item> + <item> + <p> + Calling <c>erlang:system_info/1</c> with the new argument + <c>update_cpu_info</c> will make the runtime system + reread and update the internally stored CPU information. + For more information see the documentation of <seealso + marker="erlang#update_cpu_info">erlang:system_info(update_cpu_info)</seealso>.</p> + <p> + The CPU topology is now automatically detected on Windows + systems with less than 33 logical processors. The runtime + system will now, also on Windows, by default bind + schedulers to logical processors using the + <c>default_bind</c> bind type if the amount of schedulers + is at least equal to the amount of logical processors + configured, binding of schedulers is supported, and a CPU + topology is available at startup.</p> + <p> + Own Id: OTP-8765</p> + </item> + <item> + <p> + The SMP ERTS internal child waiter thread used on Linux + system with NPTL was unintentionally disabled during + cross compilation rewrites (OTP-8323 in R13B03). It has + now been re-enabled. Enabling it again gives a slight + performance improvement.</p> + <p> + Own Id: OTP-8774</p> + </item> + <item> + <p> + <c>epmd</c> used to generate a message to the syslog when + it started up, which could be annoying. This has been + changed to only generate the message if the debug swith + is given. (Thanks to Michael Santos.)</p> + <p> + Own Id: OTP-8775</p> + </item> + <item> + <p> + The scheduler wakeup threshold is now possible to adjust + at system boot. For more information see the <seealso + marker="erl#+swt">+swt</seealso> command line argument of + <c>erl</c>.</p> + <p> + Own Id: OTP-8811</p> + </item> + <item> + <p> + The undocumented function inet:ifget/2 has been improved + to return interface hardware address (MAC) on platforms + supporting getaddrinfo() (such as BSD unixes). Note it + still does not work on all platforms for example not + Windows nor Solaris, so the function is still + undocumented.</p> + <p> + Buffer overflow and field init bugs for inet:ifget/2 and + inet:getservbyname/2 has also been fixed.</p> + <p> + Thanks to Michael Santos.</p> + <p> + Own Id: OTP-8816</p> + </item> + <item> + <p> + Optimizations for MIPS when using gcc atomics. (Thanks to + Steve Vinoski)</p> + <p> + Own Id: OTP-8834</p> + </item> + <item> + <p> + Lock optimization in timer functionality.</p> + <p> + Own Id: OTP-8835</p> + </item> + </list> + </section> + + + <section><title>Known Bugs and Problems</title> + <list> + <item> + <p>Fix epmd and build environment to build on VxWorks</p> + <p> + Own Id: OTP-8838</p> + </item> + </list> + </section> + +</section> + +<section><title>Erts 5.8</title> + + <section><title>Fixed Bugs and Malfunctions</title> + <list> + <item> + <p> + Driver threads, such as async threads, using <seealso + marker="erl_driver#ErlDrvPDL">port data locks</seealso> + peeked at the port status field without proper locking + when looking up the driver queue.</p> + <p> + Own Id: OTP-8475</p> + </item> + <item> + <p> + The use of <c>mmap()</c> was unnecessarily disabled when + cross compiling.</p> + <p> + The <c>configure</c> arguments <c>--with-ssl</c>, and + <c>--with-odbc</c> refused to accept libraries outside of + <c>$erl_xcomp_sysroot</c> when cross compiling for no + good reason.</p> + <p> + The <c>configure</c> argument <c>--with-odbc</c> didn't + handle the value <c>yes</c> correct.</p> + <p> + The <c>configure</c> arguments <c>--with-odbc</c>, and + <c>--without-odbc</c> have also been added to the + configure help.</p> + <p> + (Thanks to Steve Vinoski for reporting these issues)</p> + <p> + Own Id: OTP-8484</p> + </item> + <item> + <p> + A call to the BIF <c>unregister(RegName)</c> when a port + had the name <c>RegName</c> registered in the runtime + system without SMP support caused a runtime system crash. + (Thanks to Per Hedeland for the bugfix and test case.)</p> + <p> + Own Id: OTP-8487</p> + </item> + <item> + <p> + The runtime system crashed if fewer logical processors + were found than reported by <c>sysconf( + SC_NPROCESSORS_CONF)</c>.</p> + <p> + Own Id: OTP-8549</p> + </item> + <item> + <p> + Fix memory management bug causing crash of non-SMP + emulator with async threads enabled. The bug did first + appear in R13B03.</p> + <p> + Own Id: OTP-8591 Aux Id: seq11554 </p> + </item> + <item> + <p> + Port locks could be prematurely destroyed.</p> + <p> + Own Id: OTP-8612</p> + </item> + <item> + <p>The <c>empd</c> program could loop and consume 100% + CPU time if an unexpected error ocurred in + <c>listen()</c> or <c>accept()</c>. Now <c>epmd</c> will + terminate if a non-recoverable error occurs. (Thanks to + Michael Santos.)</p> + <p> + Own Id: OTP-8618</p> + </item> + <item> + <p> + When kernel poll has been enabled, a livelock could in + rare circumstances occur. Problem reported by Chetan + Ahuja, fix by Mikael Pettersson.</p> + <p> + Own Id: OTP-8632</p> + </item> + <item> + <p> + Windows: Closing port of program that stalled without + reading all data could deadlock scheduler thread.</p> + <p> + Own Id: OTP-8641</p> + </item> + <item> + <p> + On some combination of Montavista Linux on Cavium Octeon + processors, some socket-related system calls returned + other numbers than -1 for errors. This caused a core dump + in inet_drv.c. Now the code works around this problem.</p> + <p> + Own Id: OTP-8654</p> + </item> + <item> + <p> + Missing memory barriers in <c>erts_poll()</c> could cause + the runtime system to hang indefinitely.</p> + <p> + Own Id: OTP-8658</p> + </item> + <item> + <p> + <c>ethr_rwmutex_tryrlock()</c> acquired and refused to + acquire a lock with inverted logic. The lock was however + never acquired in a thread unsafe manner. (Thanks to JR + Zhang for noting this issue)</p> + <p> + Own Id: OTP-8662</p> + </item> + <item> + <p> + Extreme combinations of register/unregister in a highly + parallell SMP application could crash the VM. The error + is corrected.</p> + <p> + Own Id: OTP-8663</p> + </item> + <item> + <p> + On Windows, files are now opened with FILE_SHARE_DELETE + to get closer to Unix semantics.</p> + <p> + Own Id: OTP-8667</p> + </item> + <item> + <p> + <c>erlang:system_info(multi_scheduling)</c> sometimes + erroneously returned <c>enabled</c> when it should have + returned <c>blocked</c>.</p> + <p> + Own Id: OTP-8675</p> + </item> + <item> + <p> + Fix bug causing <c>erlang:decode_packet</c> and + <c>enif_make_string</c> to generate faulty strings with + negative character values for ascii values larger than + 127. (Thanks to Paul Guyot)</p> + <p> + Own Id: OTP-8685</p> + </item> + <item> + <p> + <c>open_port/2</c> with the <c>spawn</c> and + <c>spawn_executable</c> options can include an + <c>{env,Env}</c> option. In some cases unsetting + variables would not work on Unix (typically if more + variables were unset than were actually present in the + environment).</p> + <p> + Own Id: OTP-8701</p> + </item> + <item> + <p> + A user defined CPU topology set via a call to <seealso + marker="erlang#system_flag_cpu_topology">erlang:system_flag(cpu_topology, + CPUTopology)</seealso> was not properly verified, and + could in worst case cause an emulator crash. The emulator + crash could only occur when a user defined CPU topology + already existed and was redefined.</p> + <p> + Own Id: OTP-8710</p> + </item> + </list> + </section> + + + <section><title>Improvements and New Features</title> + <list> + <item> + <p> + The grammar for match specifications in ERTS users guide + only described the tracing dialect of match + specifications. An informal grammar for the ETS dialect + is added.</p> + <p> + Own Id: OTP-8086 Aux Id: seq11333 </p> + </item> + <item> + <p> + The module binary from EEP31 (and EEP9) is implemented.</p> + <p> + Own Id: OTP-8217</p> + </item> + <item> + <p> + New NIF API function <c>enif_make_new_binary</c></p> + <p> + Own Id: OTP-8474</p> + </item> + <item> + <p> + The guard BIF <c>is_boolean/1</c> (introduced in R10B) + has now been included in the lists of BIFs allowed in + guards in the Reference Manual.</p> + <p> + Own Id: OTP-8477</p> + </item> + <item> + <p> + Added function <c>zip:foldl/3</c> to iterate over zip + archives.</p> + <p> + Added functions to create and extract escripts. See + <c>escript:create/2</c> and <c>escript:extract/2</c>.</p> + <p> + The undocumented function <c>escript:foldl/3</c> has been + removed. The same functionality can be achieved with the + more flexible functions <c>escript:extract/2</c> and + <c>zip:foldl/3</c>.</p> + <p> + Record fields has been annotated with type info. Source + files as been adapted to fit within 80 chars and trailing + whitespace has been removed.</p> + <p> + Own Id: OTP-8521</p> + </item> + <item> + <p>A regular expression with many levels of parenthesis + could cause a buffer overflow. That has been corrected. + (Thanks to Michael Santos.)</p> + <p> + Own Id: OTP-8539</p> + </item> + <item> + <p> + <c>erlang:decode_packet(httph_bin,..)</c> could return + corrupt header strings or even crash the VM. This has + been fixed. It only happened on 32-bit VM if the header + name was unknown and between 16 and 20 characters long. + Sockets with simular <c>packet</c> option did not suffer + from this bug.</p> + <p> + Own Id: OTP-8548</p> + </item> + <item> + <p>New NIF features:</p> <list><item> Send messages from + a NIF, or from thread created by NIF, to any local + process (<c>enif_send</c>) </item><item> Store terms + between NIF calls (<c>enif_alloc_env</c>, + <c>enif_make_copy</c>) </item><item> Create binary terms + with user defined memory management + (<c>enif_make_resource_binary</c>) </item></list> <p>And + some incompatible changes made to the API. For more + information see the warning text in <seealso + marker="erl_nif">erl_nif(3)</seealso>.</p> + <p> + *** POTENTIAL INCOMPATIBILITY ***</p> + <p> + Own Id: OTP-8555</p> + </item> + <item> + <p>If the '<c>fop</c>' program (needed for building PDF + files) cannot not be found, it is now possible to build + the HTML and man pages anyway (there will also be dummy + PDF files with no real content created). (Thanks to + Tuncer Ayaz.)</p> + <p> + Own Id: OTP-8559</p> + </item> + <item> + <p>When defining macros the closing right parenthesis + before the dot is now mandatory.</p> + <p> + *** POTENTIAL INCOMPATIBILITY ***</p> + <p> + Own Id: OTP-8562</p> + </item> + <item> + <p>Local and imported functions now override the + auto-imported BIFs when the names clash. The pre R14 + behaviour was that auto-imported BIFs would override + local functions. To avoid that old programs change + behaviour, the following will generate an error:</p> + <list><item><p>Doing a call without explicit module name + to a local function having a name clashing with the name + of an auto-imported BIF that was present (and + auto-imported) before OTP R14A</p></item> + <item><p>Explicitly importing a function having a name + clashing with the name of an autoimported BIF that was + present (and autoimported) before OTP R14A</p></item> + <item><p>Using any form of the old compiler directive + <c>nowarn_bif_clash</c></p></item> </list> <p>If the BIF + was added or auto-imported in OTP R14A or later, + overriding it with an import or a local function will + only result in a warning,</p> <p>To resolve clashes, you + can either use the explicit module name <c>erlang</c> to + call the BIF, or you can remove the auto-import of that + specific BIF by using the new compiler directive + <c>-compile({no_auto_import,[F/A]}).</c>, which makes all + calls to the local or imported function without explicit + module name pass without warnings or errors.</p> <p>The + change makes it possible to add auto-imported BIFs + without breaking or silently changing old code in the + future. However some current code ingeniously utilizing + the old behaviour or the <c>nowarn_bif_clash</c> compiler + directive, might need changing to be accepted by the + compiler.</p> + <p> + *** POTENTIAL INCOMPATIBILITY ***</p> + <p> + Own Id: OTP-8579</p> + </item> + <item> + <p> + A bug in re that could cause certain regular expression + matches never to terminate is corrected. (Thanks to + Michael Santos and Gordon Guthrie.)</p> + <p> + Own Id: OTP-8589</p> + </item> + <item> + <p>The erlang:open_port spawn and spawn_executable + directives can include an <c>{env,Env}</c> directive to + set up environment variables for the spawned process. A + bug prevented applications from using <c>{env,Env}</c> to + set an environment variable whose value ended with a + '<c>=</c>' (equal sign) character; the trailing equal + sign was mistaken as an indication that an environment + variable was to be cleared from the environment of the + spawned process. (Thanks to Steve Vinoski.)</p> + <p> + Own Id: OTP-8614</p> + </item> + <item> + <p><c>receive</c> statements that can only read out a + newly created reference are now specially optimized so + that it will execute in constant time regardless of the + number of messages in the receive queue for the process. + That optimization will benefit calls to + <c>gen_server:call()</c>. (See <c>gen:do_call/4</c> for + an example of a receive statement that will be + optimized.)</p> + <p> + Own Id: OTP-8623</p> + </item> + <item> + <p> + The functions file:advise/4 and file:datasync/1 have been + added. (Thanks to Filipe David Manana.)</p> + <p> + Own Id: OTP-8637</p> + </item> + <item> + <p> + New NIF API functions: <c>enif_make_atom_len</c>, + <c>enif_make_existing_atom_len</c>, + <c>enif_make_string_len</c>, <c>enif_get_atom_length</c>, + <c>enif_get_list_length</c>, <c>enif_is_list</c>, + <c>enif_is_tuple</c> (by Tuncer Ayaz)</p> + <p> + Own Id: OTP-8640</p> + </item> + <item> + <p> + Support for using gcc's built-in functions for atomic + memory access has been added. This functionallity will be + used if available and no other native atomic + implementation in ERTS is available.</p> + <p> + Own Id: OTP-8659</p> + </item> + <item> + <p> + The number of spinlocks used when implementing atomic + fall-backs when no native atomic implementation is + available has been increased from 16 to 1024.</p> + <p> + Own Id: OTP-8660</p> + </item> + <item> + <p> + Writer preferred pthread read/write locks has been + enabled on Linux.</p> + <p> + Own Id: OTP-8661</p> + </item> + <item> + <p> + The runtime system will by default bind schedulers to + logical processors using the <c>default_bind</c> bind + type if the amount of schedulers are at least equal to + the amount of logical processors configured, binding of + schedulers is supported, and a CPU topology is available + at startup. </p> + <p> + <em>NOTE:</em> If the Erlang runtime system is the only + operating system process that binds threads to logical + processors, this improves the performance of the runtime + system. However, if other operating system processes (as + for example another Erlang runtime system) also bind + threads to logical processors, there might be a + performance penalty instead. If this is the case you, are + are advised to unbind the schedulers using the <seealso + marker="erl#+sbt">+sbtu</seealso> command line argument, + or by invoking <seealso + marker="erlang#system_flag_scheduler_bind_type">erlang:system_flag(scheduler_bind_type, + unbound)</seealso>.</p> + <p> + Own Id: OTP-8666</p> + </item> + <item> + <p> + The recently added BIFs erlang:min/2, erlang:max/2 and + erlang:port_command/3 are now auto-imported (as they were + originally intended to be). Due to the recent compiler + change (OTP-8579), the only impact on old code defining + it's own min/2, max/2 or port_command/3 functions will be + a warning, the local functions will still be used. The + warning can be removed by using + -compile({no_auto_import,[min/2,max/2,port_command/3]}). + in the source file.</p> + <p> + *** POTENTIAL INCOMPATIBILITY ***</p> + <p> + Own Id: OTP-8669 Aux Id: OTP-8579 </p> + </item> + <item> + <p> + There is a new option 'exclusive' to file:open/2 that + uses the OS O_EXCL flag where supported to open the file + in exclusive mode.</p> + <p> + Own Id: OTP-8670</p> + </item> + <item> + <p> + Now, binary_to_term/2 is auto-imported. This will cause a + compile warning if and only if a module has got a local + function with that name.</p> + <p> + *** POTENTIAL INCOMPATIBILITY ***</p> + <p> + Own Id: OTP-8671</p> + </item> + <item> + <p> + Alignment of scheduler data and run queues were adjusted.</p> + <p> + Own Id: OTP-8673</p> + </item> + <item> + <p>Call time breakpoint tracing</p> <list><item>Introduce + a <c>call_time</c> option to + <c>erlang:trace_pattern/3</c>.This option enables call + time breakpoint tracing on code that is executed by + processes with call tracing enabled. Call time tracing + stores the number of calls and the time spent of each + function with this trace pattern enabled. The information + can be retrieved with <c>erlang:trace_info/2</c></item> + <item>Add a scheduler array for BpData. To solve the + issue of multiple schedulers constantly updating the head + pointer to the bp data wheel, each scheduler now has its + own entrypoint to the wheel. This head pointer can be + updated without a locking being taken.</item></list> + <p>Teach call count tracing to use atomics</p> + <list><item>Call count previously used a global lock for + accessing and writing its counter in the breakpoint. This + is now changed to atomics instead.</item> <item>The + change will let call count tracing and cprof to scale + better when increasing the number of + schedulers.</item></list> + <p> + Own Id: OTP-8677</p> + </item> + <item> + <p><c>eprof</c> has been reimplemented with support in + the Erlang virtual machine and is now both faster (i.e. + slows down the code being measured less) and scales much + better. In measurements we saw speed-ups compared to the + old eprof ranging from 6 times (for sequential code that + only uses one scheduler/core) up to 84 times (for + parallel code that uses 8 cores).</p> + <p>Note: The API for the <c>eprof</c> has been cleaned up + and extended. See the documentation.</p> + <p> + *** POTENTIAL INCOMPATIBILITY ***</p> + <p> + Own Id: OTP-8706</p> + </item> + </list> + </section> + +</section> + +<section><title>Erts 5.7.5.1</title> + + <section><title>Fixed Bugs and Malfunctions</title> + <list> + <item> + <p> + Driver threads, such as async threads, using <seealso + marker="erl_driver#ErlDrvPDL">port data locks</seealso> + peeked at the port status field without proper locking + when looking up the driver queue.</p> + <p> + Own Id: OTP-8475</p> + </item> + <item> + <p> + A call to the BIF <c>unregister(RegName)</c> when a port + had the name <c>RegName</c> registered in the runtime + system without SMP support caused a runtime system crash. + (Thanks to Per Hedeland for the bugfix and test case.)</p> + <p> + Own Id: OTP-8487</p> + </item> + <item> + <p> + Fix memory management bug causing crash of non-SMP + emulator with async threads enabled. The bug did first + appear in R13B03.</p> + <p> + Own Id: OTP-8591 Aux Id: seq11554 </p> + </item> + </list> + </section> + +</section> + <section><title>Erts 5.7.5</title> <section><title>Fixed Bugs and Malfunctions</title> |