diff options
Diffstat (limited to 'erts/doc/src')
| -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/erlang.xml | 24 | ||||
| -rw-r--r-- | erts/doc/src/escript.xml | 217 | ||||
| -rw-r--r-- | erts/doc/src/notes.xml | 2 |
7 files changed, 222 insertions, 35 deletions
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/erlang.xml b/erts/doc/src/erlang.xml index 46f8df4683..c95a7005ec 100644 --- a/erts/doc/src/erlang.xml +++ b/erts/doc/src/erlang.xml @@ -2749,7 +2749,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 +2926,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> @@ -5850,9 +5850,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/notes.xml b/erts/doc/src/notes.xml index 65b836fc45..c11509131c 100644 --- a/erts/doc/src/notes.xml +++ b/erts/doc/src/notes.xml @@ -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> |