diff options
Diffstat (limited to 'erts/doc')
| -rw-r--r-- | erts/doc/src/driver.xml | 46 | ||||
| -rw-r--r-- | erts/doc/src/driver_entry.xml | 28 | ||||
| -rw-r--r-- | erts/doc/src/epmd.xml | 23 | ||||
| -rw-r--r-- | erts/doc/src/erl.xml | 83 | ||||
| -rw-r--r-- | erts/doc/src/erl_dist_protocol.xml | 2 | ||||
| -rw-r--r-- | erts/doc/src/erl_driver.xml | 94 | ||||
| -rw-r--r-- | erts/doc/src/erl_ext_dist.xml | 2 | ||||
| -rw-r--r-- | erts/doc/src/erl_nif.xml | 72 | ||||
| -rw-r--r-- | erts/doc/src/erlang.xml | 55 | ||||
| -rw-r--r-- | erts/doc/src/erlc.xml | 46 | ||||
| -rw-r--r-- | erts/doc/src/escript.xml | 10 | ||||
| -rw-r--r-- | erts/doc/src/init.xml | 13 | ||||
| -rw-r--r-- | erts/doc/src/notes.xml | 507 |
13 files changed, 837 insertions, 144 deletions
diff --git a/erts/doc/src/driver.xml b/erts/doc/src/driver.xml index 006a6160de..2b1ed398ee 100644 --- a/erts/doc/src/driver.xml +++ b/erts/doc/src/driver.xml @@ -63,7 +63,8 @@ <p>This is a simple driver for accessing a postgres database using the libpq C client library. Postgres is used because it's free and open source. For information - on postgres, refer to the website www.postgres.org.</p> + on postgres, refer to the website + <url href="http://www.postgres.org">www.postgres.org</url>.</p> <p>The driver is synchronous, it uses the synchronous calls of the client library. This is only for simplicity, and is generally not good, since it will @@ -196,18 +197,21 @@ static ErlDrvData start(ErlDrvPort port, char *command) <p>We call disconnect to log out from the database. (This should have been done from Erlang, but just in case.)</p> <code type="none"><![CDATA[ - static int do_disconnect(our_data_t* data, ei_x_buff* x); +static int do_disconnect(our_data_t* data, ei_x_buff* x); static void stop(ErlDrvData drv_data) { - do_disconnect((our_data_t*)drv_data, NULL); + our_data_t* data = (our_data_t*)drv_data; + + do_disconnect(data, NULL); + driver_free(data); } ]]></code> <p>We use the binary format only to return data to the emulator; input data is a string paramater for <c><![CDATA[connect]]></c> and <c><![CDATA[select]]></c>. The returned data consists of Erlang terms.</p> <p>The functions <c><![CDATA[get_s]]></c> and <c><![CDATA[ei_x_to_new_binary]]></c> are - utilities that is used to make the code shorter. <c><![CDATA[get_s]]></c> + utilities that are used to make the code shorter. <c><![CDATA[get_s]]></c> duplicates the string and zero-terminates it, since the postgres client library wants that. <c><![CDATA[ei_x_to_new_binary]]></c> takes an <c><![CDATA[ei_x_buff]]></c> buffer and allocates a binary and @@ -241,7 +245,7 @@ static int control(ErlDrvData drv_data, unsigned int command, char *buf, return r; } ]]></code> - <p>In <c><![CDATA[do_connect]]></c> is where we log in to the database. If the connection + <p><c><![CDATA[do_connect]]></c> is where we log in to the database. If the connection was successful we store the connection handle in our driver data, and return ok. Otherwise, we return the error message from postgres, and store <c><![CDATA[NULL]]></c> in the driver data.</p> @@ -261,7 +265,7 @@ static int do_connect(const char *s, our_data_t* data, ei_x_buff* x) } ]]></code> <p>If we are connected (if the connection handle is not <c><![CDATA[NULL]]></c>), - we log out from the database. We need to check if a we should + we log out from the database. We need to check if we should encode an ok, since we might get here from the <c><![CDATA[stop]]></c> function, which doesn't return data to the emulator.</p> <code type="none"><![CDATA[ @@ -276,7 +280,7 @@ static int do_disconnect(our_data_t* data, ei_x_buff* x) return 0; } ]]></code> - <p>We execute a query and encodes the result. Encoding is done + <p>We execute a query and encode the result. Encoding is done in another C module, <c><![CDATA[pg_encode.c]]></c> which is also provided as sample code.</p> <code type="none"><![CDATA[ @@ -288,7 +292,7 @@ static int do_select(const char* s, our_data_t* data, ei_x_buff* x) return 0; } ]]></code> - <p>Here we simply checks the result from postgres, and + <p>Here we simply check the result from postgres, and if it's data we encode it as lists of lists with column data. Everything from postgres is C strings, so we just use <c><![CDATA[ei_x_encode_string]]></c> to send @@ -389,7 +393,7 @@ disconnect(Port) -> select(Port, Query) -> binary_to_term(port_control(Port, ?DRV_SELECT, Query)). ]]></code> - <p>The api is simple: <c><![CDATA[connect/1]]></c> loads the driver, opens it + <p>The API is simple: <c><![CDATA[connect/1]]></c> loads the driver, opens it and logs on to the database, returning the Erlang port if successful, <c><![CDATA[select/2]]></c> sends a query to the driver, and returns the result, <c><![CDATA[disconnect/1]]></c> closes the @@ -414,7 +418,7 @@ select(Port, Query) -> <p>Sometimes database queries can take long time to complete, in our <c><![CDATA[pg_sync]]></c> driver, the emulator halts while the driver is doing its job. This is - often not acceptable, since no other Erlang processes + often not acceptable, since no other Erlang process gets a chance to do anything. To improve on our postgres driver, we reimplement it using the asynchronous calls in LibPQ.</p> @@ -469,7 +473,7 @@ typedef struct our_data_t { whether the driver is waiting for a connection or waiting for the result of a query. (This is needed since the entry <c><![CDATA[ready_io]]></c> will be called both when connecting and - when there is query result.)</p> + when there is a query result.)</p> <code type="none"><![CDATA[ static int do_connect(const char *s, our_data_t* data) { @@ -568,7 +572,7 @@ static void ready_io(ErlDrvData drv_data, ErlDrvEvent event) connection is successful, or error if it's not. If the connection is not yet established, we simply return; <c><![CDATA[ready_io]]></c> will be called again.</p> - <p>If we have result from a connect, indicated that we have data in + <p>If we have a result from a connect, indicated by having data in the <c><![CDATA[x]]></c> buffer, we no longer need to select on output (<c><![CDATA[ready_output]]></c>), so we remove this by calling <c><![CDATA[driver_select]]></c>.</p> @@ -627,9 +631,9 @@ return_port_data(Port) -> message queue. The function <c><![CDATA[return_port_data]]></c> above receives data from the port. Since the data is in binary format, we use <c><![CDATA[binary_to_term/1]]></c> to convert - it to Erlang term. Note that the driver is opened in - binary mode, <c><![CDATA[open_port/2]]></c> is called with the option - <c><![CDATA[[binary]]]></c>. This means that data sent from the driver + it to an Erlang term. Note that the driver is opened in + binary mode (<c><![CDATA[open_port/2]]></c> is called with the option + <c><![CDATA[[binary]]]></c>). This means that data sent from the driver to the emulator is sent as binaries. Without the <c><![CDATA[binary]]></c> option, they would have been lists of integers.</p> </section> @@ -643,15 +647,15 @@ return_port_data(Port) -> of a list of integers. For large lists (more than 100000 elements), this will take some time, so we will perform this as an asynchronous task.</p> - <p>The asynchronous api for drivers are quite complicated. First + <p>The asynchronous API for drivers is quite complicated. First of all, the work must be prepared. In our example we do this in <c><![CDATA[output]]></c>. We could have used <c><![CDATA[control]]></c> just as well, but we want some variation in our examples. In our driver, we allocate - a structure that contains all needed for the asynchronous task + a structure that contains anything that's needed for the asynchronous task to do the work. This is done in the main emulator thread. Then the asynchronous function is called from a driver thread, - separate from the main emulator thread. Note that the driver- - functions are not reentrant, so they shouldn't be used. + separate from the main emulator thread. Note that the driver-functions + are not reentrant, so they shouldn't be used. Finally, after the function is completed, the driver callback <c><![CDATA[ready_async]]></c> is called from the main emulator thread, this is where we return the result to Erlang. (We can't @@ -689,7 +693,7 @@ static ErlDrvEntry next_perm_driver_entry = { be sent later from the <c><![CDATA[ready_async]]></c> call-back.</p> <p>The <c><![CDATA[async_data]]></c> will be passed to the <c><![CDATA[do_perm]]></c> function. We do not use a <c><![CDATA[async_free]]></c> function (the last argument to - <c><![CDATA[driver_async]]></c>, it's only used if the task is cancelled + <c><![CDATA[driver_async]]></c>), it's only used if the task is cancelled programmatically.</p> <code type="none"><![CDATA[ struct our_async_data { @@ -740,7 +744,7 @@ static void ready_async(ErlDrvData drv_data, ErlDrvThreadData async_data) ErlDrvPort port = reinterpret_cast<ErlDrvPort>(drv_data); our_async_data* d = reinterpret_cast<our_async_data*>(async_data); int n = d->data.size(), result_n = n*2 + 3; - ErlDrvTermData* result = new ErlDrvTermData[result_n], * rp = result; + ErlDrvTermData *result = new ErlDrvTermData[result_n], *rp = result; for (vector<int>::iterator i = d->data.begin(); i != d->data.end(); ++i) { *rp++ = ERL_DRV_INT; diff --git a/erts/doc/src/driver_entry.xml b/erts/doc/src/driver_entry.xml index e71b48bd92..7860d83d83 100644 --- a/erts/doc/src/driver_entry.xml +++ b/erts/doc/src/driver_entry.xml @@ -4,7 +4,7 @@ <cref> <header> <copyright> - <year>2001</year><year>2010</year> + <year>2001</year><year>2011</year> <holder>Ericsson AB. All Rights Reserved.</holder> </copyright> <legalnotice> @@ -36,7 +36,7 @@ <description> <p>As of erts version 5.5.3 the driver interface has been extended (see <seealso marker="driver_entry#extended_marker">extended marker</seealso>). - The extended interface introduce + The extended interface introduces <seealso marker="erl_driver#version_management">version management</seealso>, the possibility to pass capability flags (see <seealso marker="driver_entry#driver_flags">driver flags</seealso>) @@ -45,21 +45,21 @@ <note> <p>Old drivers (compiled with an <c>erl_driver.h</c> from an earlier erts version than 5.5.3) have to be recompiled - (but does not have to use the extended interface).</p> + (but do not have to use the extended interface).</p> </note> <p>The <c>driver_entry</c> structure is a C struct that all erlang - drivers defines. It contains entry points for the erlang driver + drivers define. It contains entry points for the erlang driver that are called by the erlang emulator when erlang code accesses the driver.</p> <p> <marker id="emulator"></marker> The <seealso marker="driver_entry">erl_driver</seealso> driver - API functions needs a port handle + API functions need a port handle that identifies the driver instance (and the port in the emulator). This is only passed to the <c>start</c> function, but not to the other functions. The <c>start</c> function returns a driver-defined handle that is passed to the other functions. A - common practice is to have the <c>start</c> function allocating + common practice is to have the <c>start</c> function allocate some application-defined structure and stash the <c>port</c> handle in it, to use it later with the driver API functions.</p> <p>The driver call-back functions are called synchronously from the @@ -121,7 +121,7 @@ typedef struct erl_drv_entry { the port */ void (*ready_input)(ErlDrvData drv_data, ErlDrvEvent event); /* called when we have input from one of - the driver's handles) */ + the driver's handles */ void (*ready_output)(ErlDrvData drv_data, ErlDrvEvent event); /* called when output is possible to one of the driver's handles */ @@ -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 f01cf90a36..8c3c1e5237 100644 --- a/erts/doc/src/epmd.xml +++ b/erts/doc/src/epmd.xml @@ -116,10 +116,20 @@ <p>These options are available when starting the actual name server. The name server is normally started automatically by the <c>erl</c> command (if not already available), but it can also be started at i.e. system start-up.</p> <taglist> + <tag><c><![CDATA[-address List]]></c></tag> + <item> + <p>Let this instance of <c>epmd</c> listen only on the + comma-separated list of IP addresses and on the loopback address + (which is implicitely added to the list if it has not been + specified). This can also be set using the + <c><![CDATA[ERL_EPMD_ADDRESS]]></c> environment variable, see the + section <seealso marker="#environment_variables">Environment + variables</seealso> below.</p> + </item> <tag><c><![CDATA[-port No]]></c></tag> <item> <p>Let this instance of epmd listen to another TCP port than - default 4369. This can be also be set using the + 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> @@ -186,7 +196,7 @@ <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 be also be set using the + (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> @@ -228,6 +238,15 @@ <marker id="environment_variables"></marker> <title>Environment variables</title> <taglist> + <tag><c><![CDATA[ERL_EPMD_ADDRESS]]></c></tag> + <item> + <p>This environment variable may be set to a comma-separated + list of IP addresses, in which case the <c>epmd</c> daemon + will listen only on the specified address(es) and on the + loopback address (which is implicitely added to the list if it + has not been specified). The default behaviour is to listen on + all available IP addresses.</p> + </item> <tag><c><![CDATA[ERL_EPMD_PORT]]></c></tag> <item> <p>This environment variable can contain the port number epmd will use. diff --git a/erts/doc/src/erl.xml b/erts/doc/src/erl.xml index 09c9cf6812..514ee5ffaf 100644 --- a/erts/doc/src/erl.xml +++ b/erts/doc/src/erl.xml @@ -4,7 +4,7 @@ <comref> <header> <copyright> - <year>1996</year><year>2010</year> + <year>1996</year><year>2011</year> <holder>Ericsson AB. All Rights Reserved.</holder> </copyright> <legalnotice> @@ -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 @@ -686,7 +709,7 @@ </p></item> </taglist> <p>Binding of schedulers is currently only supported on newer - Linux, Solaris, and Windows systems.</p> + 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 @@ -914,7 +937,7 @@ <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 128.</p> + 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 @@ -981,6 +1004,15 @@ add to the code path. See <seealso marker="kernel:code">code(3)</seealso>.</p> </item> + <tag><c><![CDATA[ERL_EPMD_ADDRESS]]></c></tag> + <item> + <p>This environment variable may be set to a comma-separated + list of IP addresses, in which case the + <seealso marker="epmd">epmd</seealso> daemon + will listen only on the specified address(es) and on the + loopback address (which is implicitely added to the list if it + has not been specified).</p> + </item> <tag><c><![CDATA[ERL_EPMD_PORT]]></c></tag> <item> <p>This environment variable can contain the port number to use when @@ -993,6 +1025,49 @@ </section> <section> + <marker id="configuration"></marker> + <title>Configuration</title> + <p>The standard Erlang/OTP system can be re-configured to change the default + behavior on start-up.</p> + <taglist> + <tag>The .erlang Start-up File</tag> + <item> + <p>When Erlang/OTP is started, the system searches for a file named .erlang + in the directory where Erlang/OTP is started. If not found, the user's home + directory is searched for an .erlang file.</p> + <p>If an .erlang file is found, it is assumed to contain valid Erlang expressions. + These expressions are evaluated as if they were input to the shell.</p> + <p>A typical .erlang file contains a set of search paths, for example:</p> + <code type="none"><![CDATA[ + io:format("executing user profile in HOME/.erlang\n",[]). + code:add_path("/home/calvin/test/ebin"). + code:add_path("/home/hobbes/bigappl-1.2/ebin"). + io:format(".erlang rc finished\n",[]). + ]]></code> + </item> + <tag>user_default and shell_default</tag> + <item> + <p>Functions in the shell which are not prefixed by a module name are assumed + to be functional objects (Funs), built-in functions (BIFs), or belong to the + module user_default or shell_default.</p> + <p>To include private shell commands, define them in a module user_default and + add the following argument as the first line in the .erlang file.</p> + <code type="none"><![CDATA[ + code:load_abs("..../user_default"). + ]]></code> + </item> + <tag>erl</tag> + <item> + <p>If the contents of .erlang are changed and a private version of + user_default is defined, it is possible to customize the Erlang/OTP environment. + More powerful changes can be made by supplying command line arguments in the + start-up script erl. Refer to erl(1) and <seealso marker="init">init(3)</seealso> + for further information.</p> + </item> + </taglist> + </section> + + <section> <title>SEE ALSO</title> <p><seealso marker="init">init(3)</seealso>, <seealso marker="erl_prim_loader">erl_prim_loader(3)</seealso>, diff --git a/erts/doc/src/erl_dist_protocol.xml b/erts/doc/src/erl_dist_protocol.xml index 1fe7ac7ecd..6c725fc82d 100644 --- a/erts/doc/src/erl_dist_protocol.xml +++ b/erts/doc/src/erl_dist_protocol.xml @@ -5,7 +5,7 @@ <header> <copyright> <year>2007</year> - <year>2007</year> + <year>2011</year> <holder>Ericsson AB, All Rights Reserved</holder> </copyright> <legalnotice> diff --git a/erts/doc/src/erl_driver.xml b/erts/doc/src/erl_driver.xml index 497a2fa01d..066a2a4b92 100644 --- a/erts/doc/src/erl_driver.xml +++ b/erts/doc/src/erl_driver.xml @@ -56,16 +56,16 @@ instance is connected to an Erlang port. Every port has a port owner process. Communication with the port is normally done through the port owner process.</p> - <p>Most of the functions takes the <c>port</c> handle as an + <p>Most of the functions take the <c>port</c> handle as an argument. This identifies the driver instance. Note that this port handle must be stored by the driver, it is not given when the driver is called from the emulator (see <seealso marker="driver_entry#emulator">driver_entry</seealso>).</p> - <p>Some of the functions takes a parameter of type + <p>Some of the functions take a parameter of type <c>ErlDrvBinary</c>, a driver binary. It should be both - allocated and freed by the caller. Using a binary directly avoid + allocated and freed by the caller. Using a binary directly avoids one extra copying of data.</p> - <p>Many of the output functions has a "header buffer", with + <p>Many of the output functions have a "header buffer", with <c>hbuf</c> and <c>hlen</c> parameters. This buffer is sent as a list before the binary (or list, depending on port mode) that is sent. This is convenient when matching on messages received from @@ -92,7 +92,7 @@ with SMP support without being rewritten if driver level locking is used.</p> <note> - <p>It is assumed that drivers does not access other drivers. If + <p>It is assumed that drivers do not access other drivers. If drivers should access each other they have to provide their own mechanism for thread safe synchronization. Such "inter driver communication" is strongly discouraged.</p> @@ -113,12 +113,12 @@ call-backs may be made from different threads.</p> </note> <p>Most functions in this API are <em>not</em> thread-safe, i.e., - they may <em>not</em> be called from an arbitrary thread. Function + they may <em>not</em> be called from an arbitrary thread. Functions that are not documented as thread-safe may only be called from driver call-backs or function calls descending from a driver call-back call. Note that driver call-backs may be called from different threads. This, however, is not a problem for any - functions in this API, since the emulator have control over + function in this API, since the emulator has control over these threads.</p> <note> <p>Functions not explicitly documented as thread-safe are @@ -155,10 +155,10 @@ more information.</p> </item> <tag>Output functions</tag> - <item>With the output functions, the driver sends data back + <item>With the output functions, the driver sends data back to the emulator. They will be received as messages by the port owner process, see <c>open_port/2</c>. The vector function and the - function taking a driver binary is faster, because that avoid + function taking a driver binary are faster, because they avoid copying the data buffer. There is also a fast way of sending terms from the driver, without going through the binary term format.</item> @@ -193,14 +193,14 @@ use functionality from the POSIX thread API or the Windows native thread API. </p> - <p>The Erlang driver thread API only return error codes when it is + <p>The Erlang driver thread API only returns error codes when it is reasonable to recover from an error condition. If it isn't reasonable to recover from an error condition, the whole runtime system is terminated. For example, if a create mutex operation fails, an error code is returned, but if a lock operation on a mutex fails, the whole runtime system is terminated. </p> - <p>Note that there exist no "condition variable wait with timeout" in + <p>Note that there exists no "condition variable wait with timeout" in the Erlang driver thread API. This is due to issues with <c>pthread_cond_timedwait()</c>. When the system clock suddenly is changed, it isn't always guaranteed that you will wake up from @@ -241,7 +241,7 @@ to give you better error reports. </p> </item> - <tag>Adding / remove drivers</tag> + <tag>Adding / removing drivers</tag> <item>A driver can add and later remove drivers.</item> <tag>Monitoring processes</tag> <item>A driver can monitor a process that does not own a port.</item> @@ -262,7 +262,7 @@ could, under rare circumstances, mean that drivers have to be slightly modified. If so, this will of course be documented. <c>ERL_DRV_EXTENDED_MINOR_VERSION</c> will be incremented when - new features are added. The runtime system use the minor version + new features are added. The runtime system uses the minor version of the driver to determine what features to use. The runtime system will refuse to load a driver if the major versions differ, or if the major versions are equal and the @@ -273,7 +273,7 @@ It can, however, not make sure that it isn't incompatible. Therefore, when loading a driver that doesn't use the extended driver interface, there is a risk that it will be loaded also when - the driver is incompatible. When the driver use the extended driver + the driver is incompatible. When the driver uses the extended driver interface, the emulator can verify that it isn't of an incompatible driver version. You are therefore advised to use the extended driver interface.</p> @@ -309,7 +309,7 @@ typedef struct ErlDrvSysInfo { <seealso marker="#driver_system_info">driver_system_info()</seealso> will write the system information when passed a reference to a <c>ErlDrvSysInfo</c> structure. A description of the - fields in the structure follow: + fields in the structure follows: </p> <taglist> <tag><c>driver_major_version</c></tag> @@ -347,14 +347,6 @@ typedef struct ErlDrvSysInfo { <item>A value <c>!= 0</c> if the runtime system has SMP support; otherwise, <c>0</c>. </item> - <tag><c>thread_support</c></tag> - <item>A value <c>!= 0</c> if the runtime system has thread support; - otherwise, <c>0</c>. - </item> - <tag><c>smp_support</c></tag> - <item>A value <c>!= 0</c> if the runtime system has SMP support; - otherwise, <c>0</c>. - </item> <tag><c>async_threads</c></tag> <item>The number of async threads in the async thread pool used by <seealso marker="#driver_async">driver_async()</seealso> @@ -401,8 +393,8 @@ typedef struct ErlDrvBinary { <seealso marker="#driver_binary_dec_refc">driver_binary_dec_refc()</seealso>.</p> </note> <p>Some driver calls, such as <c>driver_enq_binary</c>, - increments the driver reference count, and others, such as - <c>driver_deq</c> decrements it.</p> + increment the driver reference count, and others, such as + <c>driver_deq</c> decrement it.</p> <p>Using a driver binary instead of a normal buffer, is often faster, since the emulator doesn't need to copy the data, only the pointer is used.</p> @@ -415,7 +407,7 @@ typedef struct ErlDrvBinary { <c>driver_outputv</c> calls, and in the queue. Also the driver call-back <seealso marker="driver_entry#outputv">outputv</seealso> uses driver binaries.</p> - <p>If the driver of some reason or another, wants to keep a + <p>If the driver for some reason or another, wants to keep a driver binary around, in a static variable for instance, the reference count should be incremented, and the binary can later be freed in the <seealso marker="driver_entry#stop">stop</seealso> call-back, with @@ -423,7 +415,7 @@ typedef struct ErlDrvBinary { <p>Note that since a driver binary is shared by the driver and the emulator, a binary received from the emulator or sent to the emulator, must not be changed by the driver.</p> - <p>From erts version 5.5 (OTP release R11B), orig_bytes is + <p>Since erts version 5.5 (OTP release R11B), orig_bytes is guaranteed to be properly aligned for storage of an array of doubles (usually 8-byte aligned).</p> </item> @@ -447,7 +439,7 @@ typedef struct ErlIOVec { int vsize; int size; SysIOVec* iov; - >ErlDrvBinary** binv; + ErlDrvBinary** binv; } ErlIOVec; </code> <p>The I/O vector used by the emulator and drivers, is a list @@ -495,17 +487,17 @@ typedef struct ErlIOVec { Currently, the only port specific data that the emulator associates with the port data lock is the driver queue.</p> <p>Normally a driver instance does not have a port data lock. If - the driver instance want to use a port data lock, it has to + the driver instance wants to use a port data lock, it has to create the port data lock by calling <seealso marker="#driver_pdl_create">driver_pdl_create()</seealso>. <em>NOTE</em>: Once the port data lock has been created, every - access to data associated with the port data lock have to be done + access to data associated with the port data lock has to be done while having the port data lock locked. The port data lock is locked, and unlocked, respectively, by use of <seealso marker="#driver_pdl_lock">driver_pdl_lock()</seealso>, and <seealso marker="#driver_pdl_unlock">driver_pdl_unlock()</seealso>.</p> <p>A port data lock is reference counted, and when the reference - count reach zero, it will be destroyed. The emulator will at + count reaches zero, it will be destroyed. The emulator will at least increment the reference count once when the lock is created and decrement it once when the port associated with the lock terminates. The emulator will also increment the @@ -545,7 +537,7 @@ typedef struct ErlIOVec { </p> <taglist> <tag>suggested_stack_size</tag> - <item>A suggestion, in kilo-words, on how large stack to use. A value less + <item>A suggestion, in kilo-words, on how large a stack to use. A value less than zero means default size. </item> </taglist> @@ -648,7 +640,7 @@ typedef struct ErlIOVec { opened.</p> <p>The data is queued in the port owner process' message queue. Note that this does not yield to the emulator. (Since - the driver and the emulator runs in the same thread.)</p> + the driver and the emulator run in the same thread.)</p> <p>The parameter <c>buf</c> points to the data to send, and <c>len</c> is the number of bytes.</p> <p>The return value for all output functions is 0. (Unless the @@ -749,7 +741,7 @@ typedef struct ErlIOVec { function <seealso marker="driver_entry#emulator">timeout</seealso> is called.</p> <p>Note that there is only one timer on each driver instance; setting a new timer will replace an older one.</p> - <p>Return value i 0 (-1 only when the <c>timeout</c> driver + <p>Return value is 0 (-1 only when the <c>timeout</c> driver function is <c>NULL</c>).</p> </desc> </func> @@ -799,20 +791,20 @@ typedef struct ErlIOVec { event object must be a socket or pipe (or other object that <c>select</c>/<c>poll</c> can use). On windows, the Win32 API function <c>WaitForMultipleObjects</c> - is used. This places other restriction on the event object. + is used. This places other restrictions on the event object. Refer to the Win32 SDK documentation.</p> <p>The <c>on</c> parameter should be <c>1</c> for setting events and <c>0</c> for clearing them.</p> - <p>The <c>mode</c> argument is bitwise-or combination of + <p>The <c>mode</c> argument is a bitwise-or combination of <c>ERL_DRV_READ</c>, <c>ERL_DRV_WRITE</c> and <c>ERL_DRV_USE</c>. - The first two specifies whether to wait for read events and/or write + The first two specify whether to wait for read events and/or write events. A fired read event will call <seealso marker="driver_entry#ready_input">ready_input</seealso> while a fired write event will call <seealso marker="driver_entry#ready_output">ready_output</seealso>. </p> <note> - <p>Some OS (Windows) does not differ between read and write events. + <p>Some OS (Windows) do not differentiate between read and write events. The call-back for a fired event then only depends on the value of <c>mode</c>.</p> </note> <p><c>ERL_DRV_USE</c> specifies if we are using the event object or if we want to close it. @@ -834,9 +826,9 @@ typedef struct ErlIOVec { as before. But it is recommended to update them to use <c>ERL_DRV_USE</c> and <c>stop_select</c> to make sure that event objects are closed in a safe way.</p> </note> - <p>The return value is 0 (Failure, -1, only if the + <p>The return value is 0 (failure, -1, only if the <c>ready_input</c>/<c>ready_output</c> is - <c>NULL</c>.</p> + <c>NULL</c>).</p> </desc> </func> <func> @@ -1076,7 +1068,7 @@ typedef struct ErlIOVec { array of <c>SysIOVec</c>s. It also returns the number of elements in <c>vlen</c>. This is the only way to get data out of the queue.</p> - <p>Nothing is remove from the queue by this function, that must be done + <p>Nothing is removed from the queue by this function, that must be done with <c>driver_deq</c>.</p> <p>The returned array is suitable to use with the Unix system call <c>writev</c>.</p> @@ -1209,7 +1201,7 @@ typedef struct ErlIOVec { <fsummary>Stop monitoring a process from a driver</fsummary> <desc> <marker id="driver_demonitor_process"></marker> - <p>This function cancels an monitor created earlier. </p> + <p>This function cancels a monitor created earlier. </p> <p>The function returns 0 if a monitor was removed and > 0 if the monitor did no longer exist.</p> </desc> @@ -1326,7 +1318,7 @@ typedef struct ErlIOVec { <p>This function signals to erlang that the driver has encountered an EOF and should be closed, unless the port was opened with the <c>eof</c> option, in that case eof is sent - to the port. Otherwise, the port is close and an + to the port. Otherwise, the port is closed and an <c>'EXIT'</c> message is sent to the port owner process.</p> <p>The return value is 0.</p> </desc> @@ -1349,8 +1341,8 @@ typedef struct ErlIOVec { (<c>driver_failure</c>).</p> <p>The driver should fail only when in severe error situations, when the driver cannot possibly keep open, for instance - buffer allocation gets out of memory. Normal errors is more - appropriate to handle with sending error codes with + buffer allocation gets out of memory. For normal errors + it is more appropriate to send error codes with <c>driver_output</c>.</p> <p>The return value is 0.</p> </desc> @@ -1371,7 +1363,7 @@ typedef struct ErlIOVec { <p>This function returns the process id of the process that made the current call to the driver. The process id can be used with <c>driver_send_term</c> to send back data to the - caller. <c>driver_caller()</c> only return valid data + caller. <c>driver_caller()</c> only returns valid data when currently executing in one of the following driver callbacks:</p> <taglist> @@ -1409,7 +1401,7 @@ typedef struct ErlIOVec { tuple, the elements are given first, and then the tuple term, with a count. Likewise for lists.</p> <p>A tuple must be specified with the number of elements. (The - elements precedes the <c>ERL_DRV_TUPLE</c> term.)</p> + elements precede the <c>ERL_DRV_TUPLE</c> term.)</p> <p>A list must be specified with the number of elements, including the tail, which is the last term preceding <c>ERL_DRV_LIST</c>.</p> @@ -1518,7 +1510,7 @@ ERL_DRV_EXT2TERM char *buf, ErlDrvUInt len }; driver_output_term(port, spec, sizeof(spec) / sizeof(spec[0])); ]]></code> - <p>If you want to pass a binary and doesn't already have the content + <p>If you want to pass a binary and don't already have the content of the binary in an <c>ErlDrvBinary</c>, you can benefit from using <c>ERL_DRV_BUF2BINARY</c> instead of creating an <c>ErlDrvBinary</c> via <c>driver_alloc_binary()</c> and then pass the binary via @@ -1565,7 +1557,7 @@ ERL_DRV_EXT2TERM char *buf, ErlDrvUInt len <em>other</em> processes than the port owner process. The <c>receiver</c> parameter specifies the process to receive the data.</p> - <p>The parameters <c>term</c> and <c>n</c> does the same thing + <p>The parameters <c>term</c> and <c>n</c> do the same thing as in <seealso marker="#driver_output_term">driver_output_term</seealso>.</p> <p>This function is only thread-safe when the emulator with SMP support is used.</p> @@ -1660,7 +1652,7 @@ ERL_DRV_EXT2TERM char *buf, ErlDrvUInt len <desc> <marker id="driver_lock_driver"></marker> <p>This function locks the driver used by the port <c>port</c> - in memory for the rest of the emulator process + in memory for the rest of the emulator process' lifetime. After this call, the driver behaves as one of Erlang's statically linked in drivers.</p> </desc> @@ -1904,7 +1896,7 @@ ERL_DRV_EXT2TERM char *buf, ErlDrvUInt len corresponding to one of the involved thread identifiers has terminated since the thread identifier was saved, the result of <c>erl_drv_equal_tids()</c> might not give - expected result. + the expected result. </p></note> <p>This function is thread-safe.</p> </desc> diff --git a/erts/doc/src/erl_ext_dist.xml b/erts/doc/src/erl_ext_dist.xml index c2d58d1ef1..fd2da2cfe3 100644 --- a/erts/doc/src/erl_ext_dist.xml +++ b/erts/doc/src/erl_ext_dist.xml @@ -5,7 +5,7 @@ <header> <copyright> <year>2007</year> - <year>2007</year> + <year>2011</year> <holder>Ericsson AB, All Rights Reserved</holder> </copyright> <legalnotice> diff --git a/erts/doc/src/erl_nif.xml b/erts/doc/src/erl_nif.xml index 27887cbdf6..4bbd4e2a54 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>2010</year> + <year>2001</year><year>2011</year> <holder>Ericsson AB. All Rights Reserved.</holder> </copyright> <legalnotice> @@ -193,9 +193,9 @@ ok A handle ("safe pointer") to this memory block can then be returned to Erlang by the use of <seealso marker="#enif_make_resource">enif_make_resource</seealso>. The term returned by <c>enif_make_resource</c> - is totally opaque in nature. It can be stored and passed between processses - on the same node, but the only real end usage is to pass it back as argument to a NIF. - The NIF can then do <seealso marker="#enif_get_resource">enif_get_resource</seealso> + is totally opaque in nature. It can be stored and passed between processes + on the same node, but the only real end usage is to pass it back as an argument to a NIF. + The NIF can then call <seealso marker="#enif_get_resource">enif_get_resource</seealso> and get back a pointer to the memory block that is guaranteed to still be valid. A resource object will not be deallocated until the last handle term has been garbage collected by the VM and the resource has been @@ -212,17 +212,7 @@ ok the garbage collector or <c>enif_release_resource</c>). Resource types are uniquely identified by a supplied name string and the name of the implementing module.</p> - <p>Resource types support upgrade in runtime by allowing a loaded NIF - library to takeover an already existing resource type and thereby - "inherit" all existing objects of that type. The destructor of the new - library will thereafter be called for the inherited objects and the - library with the old destructor function can be safely unloaded. Existing - resource objects, of a module that is upgraded, must either be deleted - or taken over by the new NIF library. The unloading of a library will be - postponed as long as there exist resource objects with a destructor - function in the library. - </p> - <p>Here is a template example of how to create and return a resource object.</p> + <marker id="enif_resource_example"/><p>Here is a template example of how to create and return a resource object.</p> <p/> <code type="none"> ERL_NIF_TERM term; @@ -240,8 +230,13 @@ ok /* resource now only owned by "Erlang" */ } return term; -} -</code> + </code> + <p>Note that once <c>enif_make_resource</c> creates the term to + return to Erlang, the code can choose to either keep its own + native pointer to the allocated struct and release it later, or + release it immediately and rely solely on the garbage collector + to eventually deallocate the resource object when it collects + the term.</p> <p>Another usage of resource objects is to create binary terms with user defined memory management. <seealso marker="#enif_make_resource_binary">enif_make_resource_binary</seealso> @@ -251,6 +246,16 @@ ok this can be a binary term consisting of data from a <c>mmap</c>'ed file. The destructor can then do <c>munmap</c> to release the memory region.</p> + <p>Resource types support upgrade in runtime by allowing a loaded NIF + library to takeover an already existing resource type and thereby + "inherit" all existing objects of that type. The destructor of the new + library will thereafter be called for the inherited objects and the + library with the old destructor function can be safely unloaded. Existing + resource objects, of a module that is upgraded, must either be deleted + or taken over by the new NIF library. The unloading of a library will be + postponed as long as there exist resource objects with a destructor + function in the library. + </p> </item> <tag>Threads and concurrency</tag> <item><p>A NIF is thread-safe without any explicit synchronization as @@ -368,7 +373,7 @@ ok environments between NIF calls. </p> <p>A <em>process independent environment</em> is created by calling <seealso marker="#enif_alloc_env">enif_alloc_env</seealso>. It can be - used to store terms beteen NIF calls and to send terms with + used to store terms between NIF calls and to send terms with <seealso marker="#enif_send">enif_send</seealso>. A process independent environment with all its terms is valid until you explicitly invalidates it with <seealso marker="#enif_free_env">enif_free_env</seealso> @@ -464,7 +469,7 @@ typedef enum { </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> @@ -539,7 +544,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> @@ -832,8 +837,14 @@ typedef enum { <fsummary>Create an opaque handle to a resource object</fsummary> <desc><p>Create an opaque handle to a memory managed resource object obtained by <seealso marker="#enif_alloc_resource">enif_alloc_resource</seealso>. - No ownership transfer is done, the resource object still needs to be released by - <seealso marker="#enif_release_resource">enif_release_resource</seealso>.</p> + No ownership transfer is done, as the resource object still needs to be released by + <seealso marker="#enif_release_resource">enif_release_resource</seealso>, + but note that the call to <c>enif_release_resource</c> can occur + immediately after obtaining the term from <c>enif_make_resource</c>, + in which case the resource object will be deallocated when the + term is garbage collected. See the + <seealso marker="#enif_resource_example">example of creating and + returning a resource object</seealso> for more details.</p> <p>Note that the only defined behaviour of using a resource term in an Erlang program is to store it and send it between processes on the same node. Other operations such as matching or <c>term_to_binary</c> @@ -857,11 +868,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 @@ -980,11 +986,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> @@ -1041,7 +1048,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> diff --git a/erts/doc/src/erlang.xml b/erts/doc/src/erlang.xml index 25c92bdbb7..19f501391f 100644 --- a/erts/doc/src/erlang.xml +++ b/erts/doc/src/erlang.xml @@ -4,7 +4,7 @@ <erlref> <header> <copyright> - <year>1996</year><year>2010</year> + <year>1996</year><year>2011</year> <holder>Ericsson AB. All Rights Reserved.</holder> </copyright> <legalnotice> @@ -2781,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> @@ -2851,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 @@ -2954,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> @@ -2969,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> @@ -3940,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> @@ -5178,7 +5219,7 @@ true</pre> <seealso marker="#system_info_scheduler_bindings">erlang:system_info(scheduler_bindings)</seealso>. </p> <p>Schedulers can currently only be bound on newer Linux, - Solaris, and Windows systems, but more systems will be + 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, @@ -5559,7 +5600,7 @@ true</pre> <item> <p>Returns the automatically detected <c>CpuTopology</c>. The emulator currently only detects the CPU topology on some newer - Linux, Solaris, and Windows systems. On Windows system with + 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 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..66e904f64f 100644 --- a/erts/doc/src/escript.xml +++ b/erts/doc/src/escript.xml @@ -4,7 +4,7 @@ <comref> <header> <copyright> - <year>2007</year><year>2010</year> + <year>2007</year><year>2011</year> <holder>Ericsson AB. All Rights Reserved.</holder> </copyright> <legalnotice> @@ -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/init.xml b/erts/doc/src/init.xml index 33364c709a..0e828389f6 100644 --- a/erts/doc/src/init.xml +++ b/erts/doc/src/init.xml @@ -67,19 +67,6 @@ </desc> </func> <func> - <name>get_args() -> [Arg]</name> - <fsummary>Get all non-flag command line arguments</fsummary> - <type> - <v>Arg = atom()</v> - </type> - <desc> - <p>Returns any plain command line arguments as a list of atoms - (possibly empty). It is recommended that - <c>get_plain_arguments/1</c> is used instead, because of - the limited length of atoms.</p> - </desc> - </func> - <func> <name>get_argument(Flag) -> {ok, Arg} | error</name> <fsummary>Get the values associated with a command line user flag</fsummary> <type> diff --git a/erts/doc/src/notes.xml b/erts/doc/src/notes.xml index 1703ce0942..102fa43c1f 100644 --- a/erts/doc/src/notes.xml +++ b/erts/doc/src/notes.xml @@ -30,6 +30,513 @@ </header> <p>This document describes the changes made to the ERTS application.</p> +<section><title>Erts 5.8.3</title> + + <section><title>Fixed Bugs and Malfunctions</title> + <list> + <item> + <p> + The scroll wheel now scrolls the werl window on Windows.</p> + <p> + Own Id: OTP-8985</p> + </item> + <item> + <p> + Some malformed distribution messages could cause VM to + crash, this is now corrected.</p> + <p> + Own Id: OTP-8993</p> + </item> + <item> + <p> + The OS function getifaddrs() can return NULL in some + address fields for e.g PPP and tunnel devices which + caused the emulator to segfault. This bug has now been + corrected.</p> + <p> + Own Id: OTP-8996</p> + </item> + <item> + <p> + The expression <<A:0>> would always produce + an empty binary, even if <c>A</c> was not an integer. + Corrected to cause a <c>badarg</c> exception if the type + of <c>A</c> is invalid. (Thanks to Zvi.)</p> + <p> + Own Id: OTP-8997</p> + </item> + <item> + <p> + A bug that potentially could cause an emulator crash when + deleting an ETS-table has been fixed. A resource leak + when hitting the maximum amount of ETS-tables allowed has + also been fixed.</p> + <p> + Own Id: OTP-8999</p> + </item> + <item> + <p> + A bug in the <c>exit/2</c> BIF could potentially cause an + emulator crash.</p> + <p> + Own Id: OTP-9005</p> + </item> + <item> + <p> + Due to a bug in glibc the runtime system could abort + while trying to destroy a mutex. The runtime system will + now issue a warning instead of aborting.</p> + <p> + Own Id: OTP-9009</p> + </item> + <item> + <p> + A bug in epmd could create strange behaviour when + listen() calls failed. This is now corrected thanks to + Steve Vinoski.</p> + <p> + Own Id: OTP-9024</p> + </item> + <item> + <p>When setting file_info the win32_driver will now + correctly set access and modified time. Previously these + entities were swapped.</p> + <p> + Own Id: OTP-9046</p> + </item> + <item> + <p> + Setting scheduler bind type to <c>unbound</c> failed if + binding of schedulers wasn't supported, or if CPU + topology wasn't present. This even though the + documentation stated that it is possible to set the bind + type to <c>unbound</c>.</p> + <p> + Own Id: OTP-9056 Aux Id: Seq11779 </p> + </item> + <item> + <p>Two problems were fixed in crash dump: The time left + for timers are now shown as unsigned integers and the + contents of ordered_set ETS tables is no longer + included.</p> + <p> + Own Id: OTP-9057</p> + </item> + <item> + <p> + The VM could fail to set IP_TOS and SO_PRIORITY in + certain situations, either because sockets were supplied + as open file descriptors, or because SO_PRIORITY by + default was set higher than the user can explicitly set + it to. Those situations are now handled.</p> + <p> + Own Id: OTP-9069</p> + </item> + <item> + <p> + Wx on MacOS X generated complains on stderr about certain + cocoa functions not beeing called from the "Main thread". + This is now corrected.</p> + <p> + Own Id: OTP-9081</p> + </item> + <item> + <p> + Fix a couple typos in driver_entry(3) (thanks to Tuncer + Ayaz).</p> + <p> + Own Id: OTP-9085</p> + </item> + <item> + <p> + Mention that "-detached" implies "-noinput"</p> + <p> + Clarify that specifying "-noinput" is unnecessary if the + "-detached" flag is given. (thanks to Holger Wei�)</p> + <p> + Own Id: OTP-9086</p> + </item> + <item> + <p> + A potential problem (found by code inspection) when + calling a fun whose code was not loaded has been fixed.</p> + <p> + Own Id: OTP-9095</p> + </item> + <item> + <p> + The emulator could get into a state where it didn't check + for I/O.</p> + <p> + Own Id: OTP-9105 Aux Id: Seq11798 </p> + </item> + <item> + <p> + Attempting to create binaries exceeding 2Gb (using for + example <c>term_to_binary/1</c>) would crash the emulator + with an attempt to allocate huge amounts of memory. + (Thanks to Jon Meredith.)</p> + <p> + Own Id: OTP-9117</p> + </item> + <item> + <p> + Fix erlang:hibernate/3 on HiPE enabled emulator (Thanks + to Paul Guyot)</p> + <p> + Own Id: OTP-9125</p> + </item> + </list> + </section> + + + <section><title>Improvements and New Features</title> + <list> + <item> + <p>From this release, the previously experimental + halfword emulator is now official. It can be enabled by + giving the <c>--enable-halfword-emulator</c> option to + the <c>configure</c> script.</p> + <p>The halfword emulator is a 64-bit application, but + uses halfwords (32-bit words) for all data in Erlang + processes, therefore using less memory and being faster + than the standard 64-bit emulator. The total size of all + BEAM code and all process data for all processes is + limited to 4Gb, but ETS tables and off-heap binaries are + only limited by the amount of available memory.</p> + <p> + Own Id: OTP-8941</p> + </item> + <item> + <p> + 32-bit atomic memory operations have been introduced + internally in the run time system, and are now used where + appropriate. There were previously only atomic memory + operations of word size available. The 32-bit atomic + memory operations slightly reduce memory consumption, and + slightly improve performance on 64-bit runtime systems.</p> + <p> + Own Id: OTP-8974</p> + </item> + <item> + <p> + Performance enhancements for looking up timer-entries and + removing timers from the wheel.</p> + <p> + Own Id: OTP-8990</p> + </item> + <item> + <p> + Write accesses to ETS tables have been optimized by + reducing the amount of atomic memory operations needed + during a write access.</p> + <p> + Own Id: OTP-9000</p> + </item> + <item> + <p> + Strange C coding in the VM made the -D_FORTIFY_SOURCE + option to gcc-4.5 react badly. The code is now cleaned up + so that it's accepted by gcc-4.5.</p> + <p> + Own Id: OTP-9025</p> + </item> + <item> + <p> + The memory footprint for loaded code has been somewhat + reduced (especially in the 64-bit BEAM machine).</p> + <p> + Own Id: OTP-9030</p> + </item> + <item> + <p> + The maximum number of allowed arguments for an Erlang + function has been lowered from 256 to 255, so that the + number of arguments can now fit in a byte.</p> + <p> + Own Id: OTP-9049</p> + </item> + <item> + <p> + Dependency generation for Makefiles has been added to the + compiler and erlc. See the manual pages for + <c>compile</c> and <c>erlc</c>. (Thanks to Jean-Sebastien + Pedron.)</p> + <p> + Own Id: OTP-9065</p> + </item> + </list> + </section> + +</section> + +<section><title>Erts 5.8.2</title> + + <section><title>Fixed Bugs and Malfunctions</title> + <list> + <item> + <p> Fix format_man_pages so it handles all man sections + and remove warnings/errors in various man pages. </p> + <p> + Own Id: OTP-8600</p> + </item> + <item> + <p> + The <c>configure</c> command line argument <seealso + marker="doc/installation_guide:INSTALL#How-to-Build-and-Install-ErlangOTP_A-Closer-Look-at-the-individual-Steps_Configuring">--enable-ethread-pre-pentium4-compatibility</seealso> + had no effect. This option is now also automatically + enabled if required on the build machine.</p> + <p> + Own Id: OTP-8847</p> + </item> + <item> + <p> + Windows 2003 and Windows XP pre SP3 would sometimes not + start the Erlang R14B VM at all due to a bug in the cpu + topology detection. The bug affects Windows only, no + other platform is even remotely affected. The bug is now + corrected.</p> + <p> + Own Id: OTP-8876</p> + </item> + <item> + <p> + The HiPE run-time in the 64-bit emulator could do a + 64-bit write to a 32-bit struct field. It happened to be + harmless on Intel/AMD processors. Corrected. (Thanks to + Mikael Pettersson.)</p> + <p> + Own Id: OTP-8877</p> + </item> + <item> + <p> + A bug in <seealso + marker="erl_driver#erl_drv_tsd_get">erl_drv_tsd_get()</seealso> + and <seealso + marker="erl_nif#enif_tsd_get">enif_tsd_get()</seealso> + could cause an emulator crash. These functions are + currently not used in OTP. That is, the crash only occur + on systems with user implemented NIF libraries, or + drivers that use one of these functions.</p> + <p> + Own Id: OTP-8889</p> + </item> + <item> + <p> + Calling <c>erlang:system_info({cpu_topology, + CpuTopologyType})</c> with another <c>CpuTopologyType</c> + element than one of the documented atoms <c>defined</c>, + <c>detected</c>, or <c>used</c> caused an emulator crash. + (Thanks to Paul Guyot)</p> + <p> + Own Id: OTP-8914</p> + </item> + <item> + <p> + The ERTS internal rwlock implementation could get into an + inconsistent state. This bug was very seldom triggered, + but could be during heavy contention. The bug was + introduced in R14B (erts-5.8.1).</p> + <p> + The bug was most likely to be triggered when using the + <c>read_concurrency</c> option on an ETS table that was + frequently accessed from multiple processes doing lots of + writes and reads. That is, in a situation where you + typically don't want to use the <c>read_concurrency</c> + option in the first place.</p> + <p> + Own Id: OTP-8925 Aux Id: OTP-8544 </p> + </item> + <item> + <p> + Tracing to port could cause an emulator crash when + unloading the trace driver.</p> + <p> + Own Id: OTP-8932</p> + </item> + <item> + <p> + Removed use of CancelIoEx on Windows that had been shown + to cause problems with some drivers.</p> + <p> + Own Id: OTP-8937</p> + </item> + <item> + <p> + The fallback implementation used when no native atomic + implementation was found did not compile. (Thanks to + Patrick Baggett, and Tuncer Ayaz)</p> + <p> + Own Id: OTP-8944</p> + </item> + <item> + <p> + Some integer values used during load balancing could + under rare circumstances wrap causing a load unbalance + between schedulers.</p> + <p> + Own Id: OTP-8950</p> + </item> + <item> + <p> + The windows VM now correctly handles appending to large + files (> 4GB).</p> + <p> + Own Id: OTP-8958</p> + </item> + <item> + <p> + Name resolving of IPv6 addresses has been implemented for + Windows versions that support it. The use of ancient + resolver flags (AI_V4MAPPED | AI_ADDRCONFIG) to the + getaddrinfo() function has been removed since e.g FreeBSD + regard mapped IPv4 addresses to be a security problem and + the semantics of the address configured flag is + uncertain.</p> + <p> + Own Id: OTP-8969</p> + </item> + </list> + </section> + + + <section><title>Improvements and New Features</title> + <list> + <item> + <p> + The help texts produced by the <c>configure</c> scripts + in the top directory and in the erts directory have been + aligned and cleaned up.</p> + <p> + Own Id: OTP-8859</p> + </item> + <item> + <p> + When the runtime system had fewer schedulers than logical + processors, the system could get an unnecessarily large + amount reader groups.</p> + <p> + Own Id: OTP-8861</p> + </item> + <item> + <p> + <c>run_rel</c> has been updated to support Solaris's + /dev/ptmx device and to load the necessary STREAMS + modules so that <c>to_erl</c> can provide terminal echo + of keyboard input. (Thanks to Ryan Tilder.)</p> + <p> + Own Id: OTP-8878</p> + </item> + <item> + <p> + The Erlang VM now supports Unicode filenames. The feature + is turned on by default on systems where Unicode + filenames are mandatory (Windows and MacOSX), but can be + enabled on other systems with the '+fnu' emulator option. + Enabling the Unicode filename feature on systems where it + is not default is however considered experimental and not + to be used for production. Together with the Unicode file + name support, the concept of "raw filenames" is + introduced, which means filenames provided without + implicit unicode encoding translation. Raw filenames are + provided as binaries, not lists. For further information, + see stdlib users guide and the chapter about using + Unicode in Erlang. Also see the file module manual page.</p> + <p> + *** POTENTIAL INCOMPATIBILITY ***</p> + <p> + Own Id: OTP-8887</p> + </item> + <item> + <p>Buffer overflows have been prevented in <c>erlc</c>, + <c>dialyzer</c>, <c>typer</c>, <c>run_test</c>, + <c>heart</c>, <c>escript</c>, and <c>erlexec</c>.</p> + (Thanks to Michael Santos.) + <p> + Own Id: OTP-8892</p> + </item> + <item> + <p> + The runtime system is now less eager to suspend processes + sending messages over the distribution. The default value + of the distribution buffer busy limit has also been + increased from 128 KB to 1 MB. This in order to improve + throughput.</p> + <p> + Own Id: OTP-8901</p> + </item> + <item> + <p> + The distribution buffer busy limit can now be configured + at system startup. For more information see the + documentation of the <c>erl</c> <seealso + marker="erl#+zdbbl">+zdbbl</seealso> command line flag. + (Thanks to Scott Lystig Fritchie)</p> + <p> + Own Id: OTP-8912</p> + </item> + <item> + <p> + The inet driver internal buffer stack implementation has + been rewritten in order to reduce lock contention.</p> + <p> + Own Id: OTP-8916</p> + </item> + <item> + <p> + New ETS option <c>compressed</c>, to enable a more + compact storage format at the expence of heavier table + operations. For test and evaluation, <c>erl +ec</c> can + be used to force compression on all ETS tables.</p> + <p> + Own Id: OTP-8922 Aux Id: seq11658 </p> + </item> + <item> + <p> + There is now a new function inet:getifaddrs/0 modeled + after C library function getifaddrs() on BSD and LInux + that reports existing interfaces and their addresses on + the host. This replaces the undocumented and unsupported + inet:getiflist/0 and inet:ifget/2.</p> + <p> + Own Id: OTP-8926</p> + </item> + <item> + <p> + Support for detection of CPU topology and binding of + schedulers on FreeBSD 8 have been added. (Thanks to Paul + Guyot)</p> + <p> + Own Id: OTP-8939</p> + </item> + <item> + <p> + Several bugs related to hibernate/3 and HiPE have been + corrected. (Thanks to Paul Guyot.)</p> + <p> + Own Id: OTP-8952</p> + </item> + <item> + <p> + Support for soft and hard links on Windows versions and + filesystems that support them is added.</p> + <p> + Own Id: OTP-8955</p> + </item> + <item> + <p> + The win32 virtual machine is now linked large address + aware. his allows the Erlang VM to use up to 3 gigs of + address space on Windows instead of the default of 2 + gigs.</p> + <p> + Own Id: OTP-8956</p> + </item> + </list> + </section> + +</section> + <section><title>Erts 5.8.1.2</title> <section><title>Fixed Bugs and Malfunctions</title> |