diff options
Diffstat (limited to 'erts/doc/src')
| -rw-r--r-- | erts/doc/src/Makefile | 11 | ||||
| -rw-r--r-- | erts/doc/src/alt_dist.xml | 8 | ||||
| -rw-r--r-- | erts/doc/src/driver.xml | 2 | ||||
| -rw-r--r-- | erts/doc/src/erl_dist_protocol.xml | 2 | ||||
| -rw-r--r-- | erts/doc/src/erl_driver.xml | 2 | ||||
| -rw-r--r-- | erts/doc/src/erl_nif.xml | 40 | ||||
| -rw-r--r-- | erts/doc/src/erlang.xml | 79 | ||||
| -rw-r--r-- | erts/doc/src/escript.xml | 217 | ||||
| -rw-r--r-- | erts/doc/src/match_spec.xml | 2 | ||||
| -rw-r--r-- | erts/doc/src/notes.xml | 4 |
10 files changed, 310 insertions, 57 deletions
diff --git a/erts/doc/src/Makefile b/erts/doc/src/Makefile index 3dfefa2001..6578923fe1 100644 --- a/erts/doc/src/Makefile +++ b/erts/doc/src/Makefile @@ -1,19 +1,19 @@ # # %CopyrightBegin% -# -# Copyright Ericsson AB 1997-2009. All Rights Reserved. -# +# +# Copyright Ericsson AB 1997-2010. All Rights Reserved. +# # The contents of this file are subject to the Erlang Public License, # Version 1.1, (the "License"); you may not use this file except in # compliance with the License. You should have received a copy of the # Erlang Public License along with this software. If not, it can be # retrieved online at http://www.erlang.org/. -# +# # Software distributed under the License is distributed on an "AS IS" # basis, WITHOUT WARRANTY OF ANY KIND, either express or implied. See # the License for the specific language governing rights and limitations # under the License. -# +# # %CopyrightEnd% # include $(ERL_TOP)/make/target.mk @@ -45,6 +45,7 @@ XML_REF1_FILES = epmd.xml \ XML_REF3_FILES = \ driver_entry.xml \ + erl_nif.xml \ erl_set_memory_block.xml \ erl_driver.xml \ erl_prim_loader.xml \ diff --git a/erts/doc/src/alt_dist.xml b/erts/doc/src/alt_dist.xml index a929aec97f..36d83a685b 100644 --- a/erts/doc/src/alt_dist.xml +++ b/erts/doc/src/alt_dist.xml @@ -434,7 +434,7 @@ (13) Word received; /* Bytes received */ (14) struct uds_data *partner; /* The partner in an accept/listen pair */ (15) struct uds_data *next; /* Next structure in list */ -(16) /* The input buffer and it's data */ +(16) /* The input buffer and its data */ (17) int buffer_size; /* The allocated size of the input buffer */ (18) int buffer_pos; /* Current position in input buffer */ (19) int header_pos; /* Where the current header is in the @@ -825,7 +825,7 @@ I/O vector itself. One can use this to allocate the binaries for the queue "manually" in the driver, but we'll just fill the binary array with NULL values (line 7) , which will make - the runtime system allocate it's own buffers when we call + the runtime system allocate its own buffers when we call <c><![CDATA[driver_enqv]]></c> (line 37).</p> <p></p> <p>The routine builds an I/O vector containing the header bytes @@ -942,7 +942,7 @@ between invocations of Erlang nodes with the same name.</item> </list> <p>The control interface gets a buffer to return its value in, - but is free to allocate it's own buffer is the provided one is + but is free to allocate its own buffer is the provided one is to small. Here is the code for <c><![CDATA[uds_control]]></c>:</p> <code type="none"><![CDATA[ ( 1) static int uds_control(ErlDrvData handle, unsigned int command, @@ -1042,7 +1042,7 @@ <c><![CDATA[net_kernel:start/1]]></c> function, which is useful as it starts the distribution on a running system, where tracing/debugging can be performed. The <c><![CDATA[net_kernel:start/1]]></c> routine takes a - list as it's single argument. The lists first element should be + list as its single argument. The lists first element should be the node name (without the "@hostname") as an atom, and the second (and last) element should be one of the atoms <c><![CDATA[shortnames]]></c> or <c><![CDATA[longnames]]></c>. In the example case <c><![CDATA[shortnames]]></c> is diff --git a/erts/doc/src/driver.xml b/erts/doc/src/driver.xml index 12c79aee90..006a6160de 100644 --- a/erts/doc/src/driver.xml +++ b/erts/doc/src/driver.xml @@ -413,7 +413,7 @@ select(Port, Query) -> <title>Sample asynchronous driver</title> <p>Sometimes database queries can take long time to complete, in our <c><![CDATA[pg_sync]]></c> driver, the emulator - halts while the driver is doing it's job. This is + halts while the driver is doing its job. This is often not acceptable, since no other Erlang processes gets a chance to do anything. To improve on our postgres driver, we reimplement it using the asynchronous diff --git a/erts/doc/src/erl_dist_protocol.xml b/erts/doc/src/erl_dist_protocol.xml index 5978af178a..1fe7ac7ecd 100644 --- a/erts/doc/src/erl_dist_protocol.xml +++ b/erts/doc/src/erl_dist_protocol.xml @@ -206,7 +206,7 @@ By default EPMD listens on port 4369. <section> <title>Unregister a node from the EPMD</title> <p> - A node unregister itself from the EPMD by simply closing the + A node unregisters itself from the EPMD by simply closing the TCP connection towards EPMD established when the node was registered. </p> </section> diff --git a/erts/doc/src/erl_driver.xml b/erts/doc/src/erl_driver.xml index 5061230a33..497a2fa01d 100644 --- a/erts/doc/src/erl_driver.xml +++ b/erts/doc/src/erl_driver.xml @@ -781,7 +781,7 @@ typedef struct ErlIOVec { <marker id="driver_get_now"></marker> <p>This function reads a timestamp into the memory pointed to by the parameter <c>now</c>. See the description of <seealso marker="#ErlDrvNowData">ErlDrvNowData</seealso> for - specification of it's fields. </p> + specification of its fields. </p> <p>The return value is 0 unless the <c>now</c> pointer is not valid, in which case it is < 0. </p> </desc> diff --git a/erts/doc/src/erl_nif.xml b/erts/doc/src/erl_nif.xml index 0dd46a951a..5ec844e2ad 100644 --- a/erts/doc/src/erl_nif.xml +++ b/erts/doc/src/erl_nif.xml @@ -161,8 +161,10 @@ ok <seealso marker="#enif_release_binary">enif_release_binary</seealso> or made read-only by transferring it to an Erlang term with <seealso marker="#enif_make_binary">enif_make_binary</seealso>. - But it does not have do happen in the same NIF call. Read-only binaries - does not have to be released.</p> + But it does not have to happen in the same NIF call. Read-only binaries + do not have to be released.</p> + <p><seealso marker="#enif_make_new_binary">enif_make_new_binary</seealso> + can be used as a shortcut to allocate and return a binary in the same NIF call.</p> <p>Binaries are sequences of whole bytes. Bitstrings with an arbitrary bit length have no support yet.</p> </item> @@ -199,7 +201,7 @@ ok library with the old destructor function can be safely unloaded. Existing resource objects, of a module that is upgraded, must either be deleted or taken over by the new NIF library. The unloading of a library will be - postponed as long as it exists resource objects with a destructor + 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> @@ -262,7 +264,7 @@ ok <item><p><c>load</c> is called when the NIF library is loaded and there is no previously loaded library for this module.</p> <p><c>*priv_data</c> can be set to point to some private data - that the library needs in able to keep a state between NIF + that the library needs in order to keep a state between NIF calls. <c>enif_priv_data()</c> will return this pointer. <c>*priv_data</c> will be initialized to NULL when <c>load</c> is called.</p> @@ -325,8 +327,8 @@ ok which a NIF call is made. This pointer should not be dereferenced in any way, but only passed on to API functions. An <c>ErlNifEnv</c> pointer is only valid until - the function, where is what supplied as argument, - returns. There is thus useless and dangerous to store <c>ErlNifEnv</c> + the function, where it was supplied as argument, + returns. It is thus useless and dangerous to store <c>ErlNifEnv</c> pointers in between NIF calls.</p> </item> <tag><marker id="ErlNifFunc"/>ErlNifFunc</tag> @@ -407,7 +409,7 @@ typedef enum { </func> <func><name><ret>int</ret><nametext>enif_alloc_binary(ErlNifEnv* env, unsigned size, ErlNifBinary* bin)</nametext></name> <fsummary>Create a new binary.</fsummary> - <desc><p>Allocate a new binary of size of <c>size</c> + <desc><p>Allocate a new binary of size <c>size</c> bytes. Initialize the structure pointed to by <c>bin</c> to refer to the allocated binary. The binary must either be released by <seealso marker="#enif_release_binary">enif_release_binary()</seealso> @@ -612,8 +614,8 @@ typedef enum { call and then as released.</p></desc> </func> <func><name><ret>ERL_NIF_TERM</ret><nametext>enif_make_double(ErlNifEnv* env, double d)</nametext></name> - <fsummary>Create an floating-point term</fsummary> - <desc><p>Create an floating-point term from a <c>double</c>.</p></desc> + <fsummary>Create a floating-point term</fsummary> + <desc><p>Create a floating-point term from a <c>double</c>.</p></desc> </func> <func><name><ret>int</ret><nametext>enif_make_existing_atom(ErlNifEnv* env, const char* name, ERL_NIF_TERM* atom)</nametext></name> <fsummary>Create an existing atom term</fsummary> @@ -644,7 +646,7 @@ typedef enum { <fsummary>Create a list term.</fsummary> <desc><p>Create an ordinary list term with length indicated by the function name. Prefer these functions (macros) over the variadic - <c>enif_make_list</c> to get compile time error if the number of + <c>enif_make_list</c> to get a compile time error if the number of arguments does not match.</p></desc> </func> <func><name><ret>ERL_NIF_TERM</ret><nametext>enif_make_list_cell(ErlNifEnv* env, ERL_NIF_TERM head, ERL_NIF_TERM tail)</nametext></name> @@ -660,6 +662,16 @@ typedef enum { <fsummary>Create an integer term from a long int</fsummary> <desc><p>Create an integer term from a <c>long int</c>.</p></desc> </func> + <func><name><ret>unsigned char*</ret><nametext>enif_make_new_binary(ErlNifEnv* env, unsigned size, ERL_NIF_TERM* termp)</nametext></name> + <fsummary>Allocate and create a new binary term</fsummary> + <desc><p>Allocate a binary of size <c>size</c> bytes and create an owning + term. The binary data is mutable until the calling NIF returns. This is a + quick way to create a new binary without having to use + <seealso marker="#ErlNifBinary">ErlNifBinary</seealso>. The drawbacks are + that the binary can not be kept between NIF calls and it can not be + reallocated.</p><p>Return a pointer to the raw binary data and set + <c>*termp</c> to the binary term.</p></desc> + </func> <func><name><ret>ERL_NIF_TERM</ret><nametext>enif_make_ref(ErlNifEnv* env)</nametext></name> <fsummary>Create a reference.</fsummary> <desc><p>Create a reference like <seealso marker="erlang#make_ref-0">erlang:make_ref/0</seealso>.</p></desc> @@ -670,7 +682,7 @@ typedef enum { obtained by <seealso marker="#enif_alloc_resource">enif_alloc_resource</seealso>. No ownership transfer is done, the resource object still needs to be released by <seealso marker="#enif_release_resource">enif_release_resource</seealso>.</p> - <p>Note that the only defined behaviour when using of a resource term in + <p>Note that the only defined behaviour of using a resource term in an Erlang program is to store it and send it between processes on the same node. Other operations such as matching or <c>term_to_binary</c> will have unpredictable (but harmless) results.</p></desc> @@ -707,7 +719,7 @@ typedef enum { <fsummary>Create a tuple term.</fsummary> <desc><p>Create a tuple term with length indicated by the function name. Prefer these functions (macros) over the variadic - <c>enif_make_tuple</c> to get compile time error if the number of + <c>enif_make_tuple</c> to get a compile time error if the number of arguments does not match.</p></desc> </func> <func><name><ret>ERL_NIF_TERM</ret><nametext>enif_make_tuple_from_array(ErlNifEnv* env, const ERL_NIF_TERM arr[], unsigned cnt)</nametext></name> @@ -762,7 +774,7 @@ typedef enum { The supplied destructor <c>dtor</c> will be called both for existing instances as well as new instances not yet created by the calling NIF library.</item> </taglist> - <p>The two flag values can be combined with bitwise-or. To avoid unintentionally + <p>The two flag values can be combined with bitwise-or. To avoid unintentional name clashes a good practice is to include the module name as part of the type <c>name</c>. The <c>dtor</c> may be <c>NULL</c> in case no destructor is needed.</p> @@ -795,7 +807,7 @@ typedef enum { </func> <func><name><ret>void</ret><nametext>enif_release_resource(ErlNifEnv* env, void* obj)</nametext></name> <fsummary>Release a resource object.</fsummary> - <desc><p>Release a resource objects obtained from <c>enif_alloc_resource</c>. + <desc><p>Release a resource object obtained from <c>enif_alloc_resource</c>. The object may still be alive if it is referred to by Erlang terms. Each call to <c>enif_release_resource</c> must correspond to a previous call to <c>enif_alloc_resource</c>. References made by <c>enif_make_resource</c> can only be released by the garbage collector.</p></desc> diff --git a/erts/doc/src/erlang.xml b/erts/doc/src/erlang.xml index 46f8df4683..e90160dfd7 100644 --- a/erts/doc/src/erlang.xml +++ b/erts/doc/src/erlang.xml @@ -253,6 +253,54 @@ iolist() = [char() | binary() | iolist()] </desc> </func> <func> + <name>binary_part(Subject, PosLen) -> binary()</name> + <fsummary>Extracts a part of a binary</fsummary> + <type> + <v>Subject = binary()</v> + <v>PosLen = {Start,Length}</v> + <v>Start = int()</v> + <v>Length = int()</v> + </type> + <desc> + <p>Extracts the part of the binary described by <c>PosLen</c>.</p> + + <p>Negative length can be used to extract bytes at the end of a binary:</p> + +<code> +1> Bin = <<1,2,3,4,5,6,7,8,9,10>>. +2> binary_part(Bin,{byte_size(Bin), -5)). +<<6,7,8,9,10>> +</code> + + <p>If <c>PosLen</c> in any way references outside the binary, a <c>badarg</c> exception is raised.</p> + + <p><c>Start</c> is zero-based, i.e:</p> +<code> +1> Bin = <<1,2,3>> +2> binary_part(Bin,{0,2}). +<<1,2>> +</code> + + <p>See the STDLIB module <c>binary</c> for details about the <c>PosLen</c> semantics.</p> + + <p>Allowed in guard tests.</p> + </desc> + </func> + <func> + <name>binary_part(Subject, Start, Length) -> binary()</name> + <fsummary>Extracts a part of a binary</fsummary> + <type> + <v>Subject = binary()</v> + <v>Start = int()</v> + <v>Length = int()</v> + </type> + <desc> + <p>The same as <c>binary_part(Subject, {Pos, Len})</c>.</p> + + <p>Allowed in guard tests.</p> + </desc> + </func> + <func> <name>binary_to_atom(Binary, Encoding) -> atom()</name> <fsummary>Convert from text representation to an atom</fsummary> <type> @@ -318,6 +366,11 @@ iolist() = [char() | binary() | iolist()] corresponding to the bytes from position <c>Start</c> to position <c>Stop</c> in <c>Binary</c>. Positions in the binary are numbered starting from 1.</p> + + <note><p>This functions indexing style of using one-based indices for + binaries is deprecated. New code should use the functions in + the STDLIB module <c>binary</c> instead. They consequently + use the same (zero-based) style of indexing.</p></note> </desc> </func> <func> @@ -2749,7 +2802,7 @@ os_prompt%</pre> <item> <p>Works like <c>{spawn, Command}</c>, but only runs - external executables. The <c>Command</c> in it's whole + external executables. The <c>Command</c> in its whole is used as the name of the executable, including any spaces. If arguments are to be passed, the <c>args</c> and <c>arg0</c> <c>PortSettings</c> can be used.</p> @@ -2926,7 +2979,7 @@ os_prompt%</pre> The standard input and standard output handles of the port program will, if this option is supplied, be opened with the flag FILE_FLAG_OVERLAPPED, so that the port program can (and has to) do - overlapped I/O on it's standard handles. This is not normally + overlapped I/O on its standard handles. This is not normally the case for simple port programs, but an option of value for the experienced Windows programmer. <em>On all other platforms, this option is silently discarded</em>.</p> @@ -5105,7 +5158,7 @@ true</pre> </p> <p><em>NOTE:</em> If other programs on the system have bound to processors, e.g. another Erlang runtime system, you - may loose performance when binding schedulers. Therefore, + may lose performance when binding schedulers. Therefore, schedulers are by default not bound.</p> <p>Schedulers can be bound in different ways. The <c>How</c> argument determines how schedulers are bound. <c>How</c> can @@ -5850,9 +5903,23 @@ true</pre> </item> <tag><c>wordsize</c></tag> <item> - <p>Returns the word size in bytes as an integer, i.e. on a - 32-bit architecture 4 is returned, and on a 64-bit - architecture 8 is returned.</p> + <p>Same as <c>{wordsize, internal}</c></p> + </item> + <tag><c>{wordsize, internal}</c></tag> + <item> + <p>Returns the size of Erlang term words in bytes as an + integer, i.e. on a 32-bit architecture 4 is returned, + and on a pure 64-bit architecture 8 is returned. On a + halfword 64-bit emulator, 4 is returned, as the Erlang + terms are stored using a virtual wordsize of half the + systems wordsize.</p> + </item> + <tag><c>{wordsize, external}</c></tag> + <item> + <p>Returns the true wordsize of the emulator, i.e. the size + of a pointer, in bytes as an integer. On a pure 32-bit + architecture 4 is returned, on both a halfword and pure + 64-bit architecture, 8 is returned.</p> </item> </taglist> <note> diff --git a/erts/doc/src/escript.xml b/erts/doc/src/escript.xml index a89449df23..44c9a5ac68 100644 --- a/erts/doc/src/escript.xml +++ b/erts/doc/src/escript.xml @@ -31,7 +31,7 @@ <com>escript</com> <comsummary>Erlang scripting support</comsummary> <description> - <p><c><![CDATA[escript]]></c> provides support for running short Erlang programs + <p><c>escript</c> provides support for running short Erlang programs without having to compile them first and an easy way to retrieve the command line arguments.</p> </description> @@ -41,10 +41,10 @@ <name>escript escript-flags script-name script-arg1 script-arg2...</name> <fsummary>Run a script written in Erlang</fsummary> <desc> - <p><c><![CDATA[escript]]></c> runs a script written in Erlang.</p> + <p><c>escript</c> runs a script written in Erlang.</p> <p>Here follows an example.</p> <pre> -$ <input>cat factorial</input> +$ <input>cat factorial</input> #!/usr/bin/env escript %% -*- erlang -*- %%! -smp enable -sname factorial -mnesia debug verbose @@ -59,11 +59,11 @@ main([String]) -> end; main(_) -> usage(). - + usage() -> io:format("usage: factorial integer\n"), halt(1). - + fac(0) -> 1; fac(N) -> N * fac(N-1). $ <input>factorial 5</input> @@ -74,9 +74,8 @@ $ <input>factorial five</input> usage: factorial integer </pre> <p>The header of the Erlang script in the example differs from a normal Erlang module. The first line is intended to be the - interpreter line, which invokes - <c><![CDATA[escript]]></c>. However if you invoke the - <c><![CDATA[escript]]></c> like this</p> + interpreter line, which invokes <c>escript</c>. However if you + invoke the <c>escript</c> like this</p> <pre> $ <input>escript factorial 5</input> </pre> <p>the contents of the first line does not matter, but it @@ -93,13 +92,13 @@ $ <input>escript factorial 5</input> </pre> %%! -smp enable -sname factorial -mnesia debug verbose</pre> <p>Such an argument line must start with <c>%%!</c> and the rest of the line will interpreted as arguments to the emulator.</p> - <p>If you know the location of the <c><![CDATA[escript]]></c> executable, the first - line can directly give the path to <c><![CDATA[escript]]></c>. For instance:</p> + <p>If you know the location of the <c>escript</c> executable, the first + line can directly give the path to <c>escript</c>. For instance:</p> <pre> #!/usr/local/bin/escript </pre> <p>As any other kind of scripts, Erlang scripts will not work on Unix platforms if the execution bit for the script file is not set. - (Use <c><![CDATA[chmod +x script-name]]></c> to turn on the execution bit.) + (Use <c>chmod +x script-name</c> to turn on the execution bit.) </p> <p>The rest of the Erlang script file may either contain @@ -108,33 +107,33 @@ $ <input>escript factorial 5</input> </pre> <p>An Erlang script file must always contain the function <em>main/1</em>. When the script is run, the - <c><![CDATA[main/1]]></c> function will be called with a list + <c>main/1</c> function will be called with a list of strings representing the arguments given to the script (not changed or interpreted in any way).</p> - <p>If the <c><![CDATA[main/1]]></c> function in the script returns successfully, + <p>If the <c>main/1</c> function in the script returns successfully, the exit status for the script will be 0. If an exception is generated during execution, a short message will be printed and the script terminated with exit status 127.</p> - <p>To return your own non-zero exit code, call <c><![CDATA[halt(ExitCode)]]></c>; + <p>To return your own non-zero exit code, call <c>halt(ExitCode)</c>; for instance:</p> <pre> halt(1).</pre> - <p>Call <c><![CDATA[escript:script_name/0]]></c> from your to - script to retrieve the pathname of the script (the pathname - is usually, but not always, absolute).</p> + <p>Call <seealso marker="#script_name_0">escript:script_name()</seealso> + from your to script to retrieve the pathname of the script + (the pathname is usually, but not always, absolute).</p> <p>If the file contains source code (as in the example above), it will be processed by the preprocessor <c>epp</c>. This means that you for example may use pre-defined macros (such as - <c><![CDATA[?MODULE]]></c>) as well as include directives like - the <c><![CDATA[-include_lib]]></c> directive. For instance, use</p> + <c>?MODULE</c>) as well as include directives like + the <c>-include_lib</c> directive. For instance, use</p> <pre> --include_lib("kernel/include/file.hrl"). </pre> +-include_lib("kernel/include/file.hrl").</pre> <p>to include the record definitions for the records used by the - <c><![CDATA[file:read_link_info/1]]></c> function.</p> + <c>file:read_link_info/1</c> function.</p> <p>The script will be checked for syntactic and semantic correctness before being run. If there are warnings (such as @@ -144,7 +143,7 @@ halt(1).</pre> 127.</p> <p>Both the module declaration and the export declaration of - the <c><![CDATA[main/1]]></c> function are optional.</p> + the <c>main/1</c> function are optional.</p> <p>By default, the script will be interpreted. You can force it to be compiled by including the following line somewhere @@ -198,6 +197,180 @@ factorial 5 = 120 </pre> </desc> </func> + <func> + <name>escript:create(FileOrBin, Sections) -> ok | {ok, binary()} | {error, term()}</name> + <fsummary>Create an escript</fsummary> + <type> + <v>FileOrBin = filename() | 'binary'</v> + <v>Sections = [Header] Body | Body</v> + <v>Header = shebang | {shebang, Shebang} + | comment | {comment, Comment} + | {emu_args, EmuArgs}</v> + <v>Shebang = string() | 'default' | 'undefined'</v> + <v>Comment = string() | 'default' | 'undefined'</v> + <v>EmuArgs = string() | 'undefined'</v> + <v>Body = {source, SourceCode} + | {beam, BeamCode} + | {archive, ZipArchive}</v> + <v>SourceCode = BeamCode = ZipArchive = binary()</v> + </type> + <desc> + <p>The <marker id="create_2"></marker> <c>create/2</c> + function creates an escript from a list of sections. The + sections can be given in any order. An escript begins with an + optional <c>Header</c> followed by a mandatory <c>Body</c>. If + the header is present, it does always begin with a + <c>shebang</c>, possibly followed by a <c>comment</c> and + <c>emu_args</c>. The <c>shebang</c> defaults to + <c>"/usr/bin/env escript"</c>. The comment defaults to + <c>"This is an -*- erlang -*- file"</c>. The created escript + can either be returned as a binary or written to file.</p> + + <p>As an example of how the function can be used, we create an + interpreted escript which uses emu_args to set some emulator + flag. In this case it happens to disable the smp_support. We + do also extract the different sections from the newly created + script:</p> + <pre> +> <input>Source = "%% Demo\nmain(_Args) ->\n io:format(erlang:system_info(smp_support)).\n".</input> +"%% Demo\nmain(_Args) ->\n io:format(erlang:system_info(smp_support)).\n" +> <input>io:format("~s\n", [Source]).</input> +%% Demo +main(_Args) -> + io:format(erlang:system_info(smp_support)). + +ok +> <input>{ok, Bin} = escript:create(binary, [shebang, comment, {emu_args, "-smp disable"}, + {source, list_to_binary(Source)}]).</input> +{ok,<<"#!/usr/bin/env escript\n%% This is an -*- erlang -*- file\n%%!-smp disabl"...>>} +> <input>file:write_file("demo.escript", Bin).</input> +ok +> <input>os:cmd("escript demo.escript").</input> +"false" +> <input>escript:extract("demo.escript", []).</input> +{ok,[{shebang,default}, {comment,default}, {emu_args,"-smp disable"}, + {source,<<"%% Demo\nmain(_Args) ->\n io:format(erlang:system_info(smp_su"...>>}]} + </pre> + + <p>An escript without header can be created like this:</p> +<pre> +> <input>file:write_file("demo.erl", + ["%% demo.erl\n-module(demo).\n-export([main/1]).\n\n", Source]).</input> +ok +> <input>{ok, _, BeamCode} = compile:file("demo.erl", [binary, debug_info]).</input> +{ok,demo, + <<70,79,82,49,0,0,2,208,66,69,65,77,65,116,111,109,0,0,0, + 79,0,0,0,9,4,100,...>>} +> <input>escript:create("demo.beam", [{beam, BeamCode}]).</input> +ok +> <input>escript:extract("demo.beam", []).</input> +{ok,[{shebang,undefined}, {comment,undefined}, {emu_args,undefined}, + {beam,<<70,79,82,49,0,0,3,68,66,69,65,77,65,116, + 111,109,0,0,0,83,0,0,0,9,...>>}]} +> <input>os:cmd("escript demo.beam").</input> +"true" +</pre> + <p>Here we create an archive script containing both Erlang + code as well as beam code. Then we iterate over all files in + the archive and collect their contents and some info about + them. + </p> +<pre> +> <input>{ok, SourceCode} = file:read_file("demo.erl").</input> +{ok,<<"%% demo.erl\n-module(demo).\n-export([main/1]).\n\n%% Demo\nmain(_Arg"...>>} +> <input>escript:create("demo.escript", + [shebang, + {archive, [{"demo.erl", SourceCode}, + {"demo.beam", BeamCode}], []}]).</input> +ok +> <input>{ok, [{shebang,default}, {comment,undefined}, {emu_args,undefined}, + {archive, ArchiveBin}]} = escript:extract("demo.escript", []).</input> +{ok,[{shebang,default}, {comment,undefined}, {emu_args,undefined}, + {{archive,<<80,75,3,4,20,0,0,0,8,0,118,7,98,60,105, + 152,61,93,107,0,0,0,118,0,...>>}]} +> <input>file:write_file("demo.zip", ArchiveBin).</input> +ok +> <input>zip:foldl(fun(N, I, B, A) -> [{N, I(), B()} | A] end, [], "demo.zip").</input> +{ok,[{"demo.beam", + {file_info,748,regular,read_write, + {{2010,3,2},{0,59,22}}, + {{2010,3,2},{0,59,22}}, + {{2010,3,2},{0,59,22}}, + 54,1,0,0,0,0,0}, + <<70,79,82,49,0,0,2,228,66,69,65,77,65,116,111,109,0,0,0, + 83,0,0,...>>}, + {"demo.erl", + {file_info,118,regular,read_write, + {{2010,3,2},{0,59,22}}, + {{2010,3,2},{0,59,22}}, + {{2010,3,2},{0,59,22}}, + 54,1,0,0,0,0,0}, + <<"%% demo.erl\n-module(demo).\n-export([main/1]).\n\n%% Demo\nmain(_Arg"...>>}]}</pre> + </desc> + </func> + <func> + <name>escript:extract(File, Options) -> {ok, Sections} | {error, term()}</name> + <fsummary>Parses an escript and extracts its sections</fsummary> + <type> + <v>File = filename()</v> + <v>Options = [] | [compile_source]</v> + <v>Sections = Headers Body</v> + <v>Headers = {shebang, Shebang} + {comment, Comment} + {emu_args, EmuArgs}</v> + <v>Shebang = string() | 'default' | 'undefined'</v> + <v>Comment = string() | 'default' | 'undefined'</v> + <v>EmuArgs = string() | 'undefined'</v> + <v>Body = {source, SourceCode} + | {source, BeamCode} + | {beam, BeamCode} + | {archive, ZipArchive}</v> + <v>SourceCode = BeamCode = ZipArchive = binary()</v> + </type> + <desc> + <p>The <marker id="extract_2"></marker> <c>extract/2</c> + function parses an escript and extracts its sections. This is + the reverse of <c>create/2</c>.</p> + + <p>All sections are returned even if they do not exist in the + escript. If a particular section happens to have the same + value as the default value, the extracted value is set to the + atom <c>default</c>. If a section is missing, the extracted + value is set to the atom <c>undefined</c>. </p> + + <p>The <c>compile_source</c> option only affects the result if + the escript contains <c>source</c> code. In that case the + Erlang code is automatically compiled and <c>{source, + BeamCode}</c> is returned instead of <c>{source, + SourceCode}</c>.</p> + + <pre> +> <input>escript:create("demo.escript", + [shebang, {archive, [{"demo.erl", SourceCode}, + {"demo.beam", BeamCode}], []}]).</input> +ok +> <input>{ok, [{shebang,default}, {comment,undefined}, {emu_args,undefined}, + {archive, ArchiveBin}]} = + escript:extract("demo.escript", []).</input> +{ok,[{{archive,<<80,75,3,4,20,0,0,0,8,0,118,7,98,60,105, + 152,61,93,107,0,0,0,118,0,...>>} + {emu_args,undefined}]} + </pre> + </desc> + </func> + <func> + <name>escript:script_name() -> File</name> + <fsummary>Returns the name of an escript</fsummary> + <type> + <v>File = filename()</v> + </type> + <desc> + <p>The <marker id="script_name_0"></marker> + <c>script_name/0</c> function returns the name of the escript + being executed. If the function is invoked outside the context + of an escript, the behavior is undefined.</p> + </desc> + </func> </funcs> <section> diff --git a/erts/doc/src/match_spec.xml b/erts/doc/src/match_spec.xml index b9f955e4db..d6492198ca 100644 --- a/erts/doc/src/match_spec.xml +++ b/erts/doc/src/match_spec.xml @@ -530,7 +530,7 @@ the atom 'strider' and the tuple arity is 3 and return the whole object.</p> <code type="none"><![CDATA[ -[{{strider,'_'.'_'}, +[{{strider,'_','_'}, [], ['$_']}] ]]></code> diff --git a/erts/doc/src/notes.xml b/erts/doc/src/notes.xml index 65b836fc45..a4867adf22 100644 --- a/erts/doc/src/notes.xml +++ b/erts/doc/src/notes.xml @@ -109,7 +109,7 @@ <item> <p>A number of bugs concerning re and unicode are corrected:</p> - <p>re:compile no longer looses unicode option, which also + <p>re:compile no longer loses unicode option, which also fixes bug in re:split.</p> <p>re:replace now handles unicode charlist replacement argument</p> @@ -4681,7 +4681,7 @@ </item> <item> <p>The runtime system with SMP support did not slowly adjust - it's view of time when the system time suddenly changed.</p> + its view of time when the system time suddenly changed.</p> <p>Timeouts could sometimes timeout too early on the runtime system with SMP support.</p> <p>Own Id: OTP-6202</p> |