diff options
Diffstat (limited to 'lib/stdlib/doc/src')
24 files changed, 277 insertions, 92 deletions
diff --git a/lib/stdlib/doc/src/binary.xml b/lib/stdlib/doc/src/binary.xml index c5eb81a86a..c81023862e 100644 --- a/lib/stdlib/doc/src/binary.xml +++ b/lib/stdlib/doc/src/binary.xml @@ -485,7 +485,7 @@ <code> 1> Bin = <<1,2,3,4,5,6,7,8,9,10>>. -2> binary:part(Bin,{byte_size(Bin), -5)). +2> binary:part(Bin,{byte_size(Bin), -5}). <<6,7,8,9,10>> </code> diff --git a/lib/stdlib/doc/src/calendar.xml b/lib/stdlib/doc/src/calendar.xml index 36f0c03162..075c7f9c78 100644 --- a/lib/stdlib/doc/src/calendar.xml +++ b/lib/stdlib/doc/src/calendar.xml @@ -4,7 +4,7 @@ <erlref> <header> <copyright> - <year>1996</year><year>2009</year> + <year>1996</year><year>2011</year> <holder>Ericsson AB. All Rights Reserved.</holder> </copyright> <legalnotice> @@ -63,6 +63,14 @@ given as local time, they must be converted to universal time, in order to get the correct value of the elapsed time between epochs. Use of the function <c>time_difference/2</c> is discouraged.</p> + <p>There exists different definitions for the week of the year. + The calendar module contains a week of the year implementation + which conforms to the ISO 8601 standard. Since the week number for + a given date can fall on the previous, the current or on the next + year it is important to provide the information which year is it + together with the week number. The function <c>iso_week_number/0</c> + and <c>iso_week_number/1</c> returns a tuple of the year and the + week number.</p> </description> <section> @@ -154,6 +162,30 @@ time() = {Hour, Minute, Second} </desc> </func> <func> + <name>iso_week_number() -> IsoWeekNumber</name> + <fsummary>Compute the iso week number for the actual date</fsummary> + <type> + <v>IsoWeekNumber = {int(), int()}</v> + </type> + <desc> + <p>This function returns the tuple {Year, WeekNum} representing + the iso week number for the actual date. For determining the + actual date, the function <c>local_time/0</c> is used.</p> + </desc> + </func> + <func> + <name>iso_week_number(Date) -> IsoWeekNumber</name> + <fsummary>Compute the iso week number for the given date</fsummary> + <type> + <v>Date = date()</v> + <v>IsoWeekNumber = {int(), int()}</v> + </type> + <desc> + <p>This function returns the tuple {Year, WeekNum} representing + the iso week number for the given date.</p> + </desc> + </func> + <func> <name>last_day_of_the_month(Year, Month) -> int()</name> <fsummary>Compute the number of days in a month</fsummary> <desc> diff --git a/lib/stdlib/doc/src/dict.xml b/lib/stdlib/doc/src/dict.xml index ebcd2eed09..0cc76e0c78 100644 --- a/lib/stdlib/doc/src/dict.xml +++ b/lib/stdlib/doc/src/dict.xml @@ -4,7 +4,7 @@ <erlref> <header> <copyright> - <year>1996</year><year>2009</year> + <year>1996</year><year>2011</year> <holder>Ericsson AB. All Rights Reserved.</holder> </copyright> <legalnotice> @@ -55,10 +55,8 @@ dictionary() </type> <desc> <p>This function appends a new <c>Value</c> to the current list - of values associated with <c>Key</c>. An exception is - generated if the initial value associated with <c>Key</c> is - not a list of values.</p> - </desc> + of values associated with <c>Key</c>.</p> + </desc> </func> <func> <name>append_list(Key, ValList, Dict1) -> Dict2</name> @@ -165,8 +163,8 @@ dictionary() <v>Dict = dictionary()</v> </type> <desc> - <p>This function converts the key/value list <c>List</c> to a - dictionary.</p> + <p>This function converts the <c>Key</c> - <c>Value</c> list + <c>List</c> to a dictionary.</p> </desc> </func> <func> @@ -270,7 +268,7 @@ merge(Fun, D1, D2) -> <v>Dict1 = Dict2 = dictionary()</v> </type> <desc> - <p>Update the a value in a dictionary by calling <c>Fun</c> on + <p>Update a value in a dictionary by calling <c>Fun</c> on the value to get a new value. An exception is generated if <c>Key</c> is not present in the dictionary.</p> </desc> @@ -285,7 +283,7 @@ merge(Fun, D1, D2) -> <v>Dict1 = Dict2 = dictionary()</v> </type> <desc> - <p>Update the a value in a dictionary by calling <c>Fun</c> on + <p>Update a value in a dictionary by calling <c>Fun</c> on the value to get a new value. If <c>Key</c> is not present in the dictionary then <c>Initial</c> will be stored as the first value. For example <c>append/3</c> could be defined diff --git a/lib/stdlib/doc/src/erl_expand_records.xml b/lib/stdlib/doc/src/erl_expand_records.xml index 7fb03e7c50..c93248493f 100644 --- a/lib/stdlib/doc/src/erl_expand_records.xml +++ b/lib/stdlib/doc/src/erl_expand_records.xml @@ -5,7 +5,7 @@ <header> <copyright> <year>2005</year> - <year>2007</year> + <year>2011</year> <holder>Ericsson AB, All Rights Reserved</holder> </copyright> <legalnotice> diff --git a/lib/stdlib/doc/src/erl_internal.xml b/lib/stdlib/doc/src/erl_internal.xml index 906b95deb7..732d77c3ae 100644 --- a/lib/stdlib/doc/src/erl_internal.xml +++ b/lib/stdlib/doc/src/erl_internal.xml @@ -5,7 +5,7 @@ <header> <copyright> <year>1996</year> - <year>2007</year> + <year>2011</year> <holder>Ericsson AB, All Rights Reserved</holder> </copyright> <legalnotice> diff --git a/lib/stdlib/doc/src/erl_pp.xml b/lib/stdlib/doc/src/erl_pp.xml index 6b15c5afd3..1fdda48893 100644 --- a/lib/stdlib/doc/src/erl_pp.xml +++ b/lib/stdlib/doc/src/erl_pp.xml @@ -5,7 +5,7 @@ <header> <copyright> <year>1996</year> - <year>2007</year> + <year>2011</year> <holder>Ericsson AB, All Rights Reserved</holder> </copyright> <legalnotice> diff --git a/lib/stdlib/doc/src/filelib.xml b/lib/stdlib/doc/src/filelib.xml index 969aff4fcb..fab68ae77c 100644 --- a/lib/stdlib/doc/src/filelib.xml +++ b/lib/stdlib/doc/src/filelib.xml @@ -4,7 +4,7 @@ <erlref> <header> <copyright> - <year>2003</year><year>2010</year> + <year>2003</year><year>2011</year> <holder>Ericsson AB. All Rights Reserved.</holder> </copyright> <legalnotice> @@ -44,7 +44,7 @@ <section> <title>DATA TYPES</title> <code type="none"> -filename() = = string() | atom() | DeepList | RawFilename +filename() = string() | atom() | DeepList | RawFilename DeepList = [char() | atom() | DeepList] RawFilename = binary() If VM is in unicode filename mode, string() and char() are allowed to be > 255. @@ -105,7 +105,7 @@ dirname() = filename()</code> interpreted as Unicode may be encountered, in which case the <c>fun()</c> must be prepared to handle raw file names (i.e. binaries). If the regular expression contains - codepoints beyond 255, it will not match file names that does + codepoints beyond 255, it will not match file names that do not conform to the expected character encoding (i.e. are not encoded in valid UTF-8).</p> diff --git a/lib/stdlib/doc/src/io.xml b/lib/stdlib/doc/src/io.xml index efbb1fc078..41e3e92c59 100644 --- a/lib/stdlib/doc/src/io.xml +++ b/lib/stdlib/doc/src/io.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> @@ -81,7 +81,8 @@ charlist() = [unicode_char() | unicode_binary() | charlist()] </section> <funcs> <func> - <name>columns([IoDevice]) -> {ok,int()} | {error, enotsup}</name> + <name>columns() -> {ok,int()} | {error, enotsup}</name> + <name>columns(IoDevice) -> {ok,int()} | {error, enotsup}</name> <fsummary>Get the number of columns of a device</fsummary> <type> <v>IoDevice = io_device()</v> @@ -94,7 +95,8 @@ charlist() = [unicode_char() | unicode_binary() | charlist()] </desc> </func> <func> - <name>put_chars([IoDevice,] IoData) -> ok</name> + <name>put_chars(IoData) -> ok</name> + <name>put_chars(IoDevice, IoData) -> ok</name> <fsummary>Write a list of characters</fsummary> <type> <v>IoDevice = io_device()</v> @@ -106,7 +108,8 @@ charlist() = [unicode_char() | unicode_binary() | charlist()] </desc> </func> <func> - <name>nl([IoDevice]) -> ok</name> + <name>nl() -> ok</name> + <name>nl(IoDevice) -> ok</name> <fsummary>Write a newline</fsummary> <type> <v>IoDevice = io_device()</v> @@ -116,7 +119,8 @@ charlist() = [unicode_char() | unicode_binary() | charlist()] </desc> </func> <func> - <name>get_chars([IoDevice,] Prompt, Count) -> Data | eof</name> + <name>get_chars(Prompt, Count) -> Data | eof</name> + <name>get_chars(IoDevice, Prompt, Count) -> Data | eof</name> <fsummary>Read a specified number of characters</fsummary> <type> <v>IoDevice = io_device()</v> @@ -150,7 +154,8 @@ charlist() = [unicode_char() | unicode_binary() | charlist()] </desc> </func> <func> - <name>get_line([IoDevice,] Prompt) -> Data | eof | {error,Reason}</name> + <name>get_line(Prompt) -> Data | eof | {error,Reason}</name> + <name>get_line(IoDevice, Prompt) -> Data | eof | {error,Reason}</name> <fsummary>Read a line</fsummary> <type> <v>IoDevice = io_device()</v> @@ -183,7 +188,8 @@ charlist() = [unicode_char() | unicode_binary() | charlist()] </desc> </func> <func> - <name>getopts([IoDevice]) -> Opts</name> + <name>getopts() -> Opts</name> + <name>getopts(IoDevice) -> Opts</name> <fsummary>Get the supported options and values from an I/O-server</fsummary> <type> <v>IoDevice = io_device()</v> @@ -210,7 +216,8 @@ charlist() = [unicode_char() | unicode_binary() | charlist()] </desc> </func> <func> - <name>setopts([IoDevice,] Opts) -> ok | {error, Reason}</name> + <name>setopts(Opts) -> ok | {error, Reason}</name> + <name>setopts(IoDevice, Opts) -> ok | {error, Reason}</name> <fsummary>Set options</fsummary> <type> <v>IoDevice = io_device()</v> @@ -281,7 +288,8 @@ charlist() = [unicode_char() | unicode_binary() | charlist()] </desc> </func> <func> - <name>write([IoDevice,] Term) -> ok</name> + <name>write(Term) -> ok</name> + <name>write(IoDevice, Term) -> ok</name> <fsummary>Write a term</fsummary> <type> <v>IoDevice = io_device()</v> @@ -293,7 +301,8 @@ charlist() = [unicode_char() | unicode_binary() | charlist()] </desc> </func> <func> - <name>read([IoDevice,] Prompt) -> Result</name> + <name>read(Prompt) -> Result</name> + <name>read(IoDevice, Prompt) -> Result</name> <fsummary>Read a term</fsummary> <type> <v>IoDevice = io_device()</v> @@ -356,9 +365,11 @@ charlist() = [unicode_char() | unicode_binary() | charlist()] </func> <func> <name>fwrite(Format) -></name> - <name>fwrite([IoDevice,] Format, Data) -> ok</name> + <name>fwrite(Format, Data) -> ok</name> + <name>fwrite(IoDevice, Format, Data) -> ok</name> <name>format(Format) -></name> - <name>format([IoDevice,] Format, Data) -> ok</name> + <name>format(Format, Data) -> ok</name> + <name>format(IoDevice, Format, Data) -> ok</name> <fsummary>Write formatted output</fsummary> <type> <v>IoDevice = io_device()</v> @@ -464,9 +475,9 @@ ok</pre> <p>Prints the argument with the <c>string</c> syntax. The argument is, if no Unicode translation modifier is present, an <seealso marker="erts:erlang#iolist_definition">I/O list</seealso>, a binary, or an atom. If the Unicode translation modifier ('t') is in effect, the argument is chardata(), meaning that binaries are in UTF-8. The characters - are printed without quotes. In this format, the printed - argument is truncated to the given precision and field - width.</p> + are printed without quotes. The string is first truncated + by the given precision and then padded and justified + to the given field width. The default precision is the field width.</p> <p>This format can be used for printing any object and truncating the output so it fits a specified field:</p> <pre> @@ -475,6 +486,8 @@ ok</pre> ok 4> <input>io:fwrite("|~10s|~n", [io_lib:write({hey, hey, hey})]).</input> |{hey,hey,h| +5> <input>io:fwrite("|~-10.8s|~n", [io_lib:write({hey, hey, hey})]).</input> +|{hey,hey | ok</pre> <p>A list with integers larger than 255 is considered an error if the Unicode translation modifier is not given:</p> <pre> @@ -660,7 +673,8 @@ ok </desc> </func> <func> - <name>fread([IoDevice,] Prompt, Format) -> Result</name> + <name>fread(Prompt, Format) -> Result</name> + <name>fread(IoDevice, Prompt, Format) -> Result</name> <fsummary>Read formatted input</fsummary> <type> <v>IoDevice = io_device()</v> @@ -820,7 +834,8 @@ enter><input>:</input> <input>alan</input> <input>:</input> <input>joe</in </desc> </func> <func> - <name>rows([IoDevice]) -> {ok,int()} | {error, enotsup}</name> + <name>rows() -> {ok,int()} | {error, enotsup}</name> + <name>rows(IoDevice) -> {ok,int()} | {error, enotsup}</name> <fsummary>Get the number of rows of a device</fsummary> <type> <v>IoDevice = io_device()</v> @@ -834,7 +849,8 @@ enter><input>:</input> <input>alan</input> <input>:</input> <input>joe</in </func> <func> <name>scan_erl_exprs(Prompt) -></name> - <name>scan_erl_exprs([IoDevice,] Prompt, StartLine) -> Result</name> + <name>scan_erl_exprs(Prompt, StartLine) -> Result</name> + <name>scan_erl_exprs(IoDevice, Prompt, StartLine) -> Result</name> <fsummary>Read and tokenize Erlang expressions</fsummary> <type> <v>IoDevice = io_device()</v> @@ -877,7 +893,8 @@ enter><input>1.0er.</input> </func> <func> <name>scan_erl_form(Prompt) -></name> - <name>scan_erl_form([IoDevice,] Prompt, StartLine) -> Result</name> + <name>scan_erl_form(Prompt, StartLine) -> Result</name> + <name>scan_erl_form(IoDevice, Prompt, StartLine) -> Result</name> <fsummary>Read and tokenize an Erlang form</fsummary> <type> <v>IoDevice = io_device()</v> @@ -900,7 +917,8 @@ enter><input>1.0er.</input> </func> <func> <name>parse_erl_exprs(Prompt) -></name> - <name>parse_erl_exprs([IoDevice,] Prompt, StartLine) -> Result</name> + <name>parse_erl_exprs(Prompt, StartLine) -> Result</name> + <name>parse_erl_exprs(IoDevice, Prompt, StartLine) -> Result</name> <fsummary>Read, tokenize and parse Erlang expressions</fsummary> <type> <v>IoDevice = io_device()</v> @@ -943,7 +961,8 @@ enter><input>abc("hey".</input> </func> <func> <name>parse_erl_form(Prompt) -></name> - <name>parse_erl_form([IoDevice,] Prompt, StartLine) -> Result</name> + <name>parse_erl_form(Prompt, StartLine) -> Result</name> + <name>parse_erl_form(IoDevice, Prompt, StartLine) -> Result</name> <fsummary>Read, tokenize and parse an Erlang form</fsummary> <type> <v>IoDevice = io_device()</v> diff --git a/lib/stdlib/doc/src/io_protocol.xml b/lib/stdlib/doc/src/io_protocol.xml index a97d996d98..3e8ab1affc 100644 --- a/lib/stdlib/doc/src/io_protocol.xml +++ b/lib/stdlib/doc/src/io_protocol.xml @@ -5,7 +5,7 @@ <header> <copyright> <year>1999</year> - <year>2009</year> + <year>2011</year> <holder>Ericsson AB. All Rights Reserved.</holder> </copyright> <legalnotice> diff --git a/lib/stdlib/doc/src/log_mf_h.xml b/lib/stdlib/doc/src/log_mf_h.xml index 198a55a63b..f8e11339a7 100644 --- a/lib/stdlib/doc/src/log_mf_h.xml +++ b/lib/stdlib/doc/src/log_mf_h.xml @@ -5,7 +5,7 @@ <header> <copyright> <year>1996</year> - <year>2007</year> + <year>2011</year> <holder>Ericsson AB, All Rights Reserved</holder> </copyright> <legalnotice> diff --git a/lib/stdlib/doc/src/math.xml b/lib/stdlib/doc/src/math.xml index 990a6b4024..02e4d6e495 100644 --- a/lib/stdlib/doc/src/math.xml +++ b/lib/stdlib/doc/src/math.xml @@ -5,7 +5,7 @@ <header> <copyright> <year>1996</year> - <year>2007</year> + <year>2011</year> <holder>Ericsson AB, All Rights Reserved</holder> </copyright> <legalnotice> diff --git a/lib/stdlib/doc/src/notes.xml b/lib/stdlib/doc/src/notes.xml index 940044d0a8..8cd499f960 100644 --- a/lib/stdlib/doc/src/notes.xml +++ b/lib/stdlib/doc/src/notes.xml @@ -30,6 +30,115 @@ </header> <p>This document describes the changes made to the STDLIB application.</p> +<section><title>STDLIB 1.17.3</title> + + <section><title>Fixed Bugs and Malfunctions</title> + <list> + <item> + <p> + Two bugs in io:format for ~F.~Ps has been corrected. When + length(S) >= abs(F) > P, the precision P was incorrectly + ignored. When F == P > lenght(S) the result was + incorrectly left adjusted. Bug found by Ali Yakout who + also provided a fix.</p> + <p> + Own Id: OTP-8989 Aux Id: seq11741 </p> + </item> + <item> + <p>Fix exception generation in the io module + <p> + Some functions did not generate correct badarg exception + on a badarg exception.</p></p> + <p> + Own Id: OTP-9045</p> + </item> + <item> + <p> + Fixes to the dict and orddict module documentation</p> + <p> + Fixed grammar and one inconsistency (Key - Value instead + of key/value, since everywhere else the former is used). + (thanks to Filipe David Manana)</p> + <p> + Own Id: OTP-9083</p> + </item> + <item> + <p> + Add ISO week number calculation functions to the calendar + module in stdlib</p> + <p> + This new feature adds the missing week number function to + the calendar module of the stdlib application. The + implementation conforms to the ISO 8601 standard. The new + feature has been implemented tested and documented + (thanks to Imre Horvath).</p> + <p> + Own Id: OTP-9087</p> + </item> + </list> + </section> + + + <section><title>Improvements and New Features</title> + <list> + <item> + <p> + Implement the 'MAY' clauses from RFC4648 regarding the + pad character to make mime_decode() and + mime_decode_to_string() functions more tolerant of badly + padded base64. The RFC is quoted below for easy + reference.</p> + <p> + "RFC4648 Section 3.3 with reference to MIME decoding: + Furthermore, such specifications MAY ignore the pad + character, "=", treating it as non-alphabet data, if it + is present before the end of the encoded data. If more + than the allowed number of pad characters is found at the + end of the string (e.g., a base 64 string terminated with + "==="), the excess pad characters MAY also be ignored."</p> + <p> + Own Id: OTP-9020</p> + </item> + <item> + <p> + Supervisors will no longer save start parameters for + temporary processes as they will not be restarted. In the + case of simple_one_for_one workers such as ssl-connection + processes this will substantial reduce the memory + footprint of the supervisor.</p> + <p> + Own Id: OTP-9064</p> + </item> + <item> + <p> + When running escript it is now possible to add the -n + flag and the escript will be compiled using +native.</p> + <p> + Own Id: OTP-9076</p> + </item> + </list> + </section> + +</section> + +<section><title>STDLIB 1.17.2.1</title> + + <section><title>Fixed Bugs and Malfunctions</title> + <list> + <item> + <p> + Several type specifications for standard libraries were + wrong in the R14B01 release. This is now corrected. The + corrections concern types in re,io,filename and the + module erlang itself.</p> + <p> + Own Id: OTP-9008</p> + </item> + </list> + </section> + +</section> + <section><title>STDLIB 1.17.2</title> <section><title>Fixed Bugs and Malfunctions</title> diff --git a/lib/stdlib/doc/src/orddict.xml b/lib/stdlib/doc/src/orddict.xml index 08c808f822..1b8b74534b 100644 --- a/lib/stdlib/doc/src/orddict.xml +++ b/lib/stdlib/doc/src/orddict.xml @@ -4,7 +4,7 @@ <erlref> <header> <copyright> - <year>2000</year><year>2009</year> + <year>2000</year><year>2011</year> <holder>Ericsson AB. All Rights Reserved.</holder> </copyright> <legalnotice> @@ -172,8 +172,8 @@ ordered_dictionary() <v>Orddict = ordered_dictionary()</v> </type> <desc> - <p>This function converts the key/value list <c>List</c> to a - dictionary.</p> + <p>This function converts the <c>Key</c> - <c>Value</c> list + <c>List</c> to a dictionary.</p> </desc> </func> <func> @@ -277,7 +277,7 @@ merge(Fun, D1, D2) -> <v>Orddict1 = Orddict2 = ordered_dictionary()</v> </type> <desc> - <p>Update the a value in a dictionary by calling <c>Fun</c> on + <p>Update a value in a dictionary by calling <c>Fun</c> on the value to get a new value. An exception is generated if <c>Key</c> is not present in the dictionary.</p> </desc> @@ -292,7 +292,7 @@ merge(Fun, D1, D2) -> <v>Orddict1 = Orddict2 = ordered_dictionary()</v> </type> <desc> - <p>Update the a value in a dictionary by calling <c>Fun</c> on + <p>Update a value in a dictionary by calling <c>Fun</c> on the value to get a new value. If <c>Key</c> is not present in the dictionary then <c>Initial</c> will be stored as the first value. For example <c>append/3</c> could be defined diff --git a/lib/stdlib/doc/src/part_notes_history.xml b/lib/stdlib/doc/src/part_notes_history.xml index 744b009583..5e055ee606 100644 --- a/lib/stdlib/doc/src/part_notes_history.xml +++ b/lib/stdlib/doc/src/part_notes_history.xml @@ -5,7 +5,7 @@ <header> <copyright> <year>2006</year> - <year>2007</year> + <year>2011</year> <holder>Ericsson AB, All Rights Reserved</holder> </copyright> <legalnotice> diff --git a/lib/stdlib/doc/src/pg.xml b/lib/stdlib/doc/src/pg.xml index 66b9702ae0..b174d4f7d4 100644 --- a/lib/stdlib/doc/src/pg.xml +++ b/lib/stdlib/doc/src/pg.xml @@ -5,7 +5,7 @@ <header> <copyright> <year>1996</year> - <year>2007</year> + <year>2011</year> <holder>Ericsson AB, All Rights Reserved</holder> </copyright> <legalnotice> diff --git a/lib/stdlib/doc/src/re.xml b/lib/stdlib/doc/src/re.xml index 056e7bc9b9..9091035392 100644 --- a/lib/stdlib/doc/src/re.xml +++ b/lib/stdlib/doc/src/re.xml @@ -5,7 +5,7 @@ <header> <copyright> <year>2007</year> - <year>2008</year> + <year>2011</year> <holder>Ericsson AB, All Rights Reserved</holder> </copyright> <legalnotice> diff --git a/lib/stdlib/doc/src/shell_default.xml b/lib/stdlib/doc/src/shell_default.xml index 4f8cc6c5bb..f7e7d5388a 100644 --- a/lib/stdlib/doc/src/shell_default.xml +++ b/lib/stdlib/doc/src/shell_default.xml @@ -5,7 +5,7 @@ <header> <copyright> <year>1996</year> - <year>2007</year> + <year>2011</year> <holder>Ericsson AB, All Rights Reserved</holder> </copyright> <legalnotice> diff --git a/lib/stdlib/doc/src/supervisor.xml b/lib/stdlib/doc/src/supervisor.xml index 45fa0847a8..d6203bdaa0 100644 --- a/lib/stdlib/doc/src/supervisor.xml +++ b/lib/stdlib/doc/src/supervisor.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> @@ -83,11 +83,17 @@ supervisor, where all child processes are dynamically added instances of the same process type, i.e. running the same code.</p> - <p>The functions <c>terminate_child/2</c>, <c>delete_child/2</c> + <p>The functions <c>delete_child/2</c> and <c>restart_child/2</c> are invalid for <c>simple_one_for_one</c> supervisors and will return <c>{error,simple_one_for_one}</c> if the specified supervisor uses this restart strategy.</p> + <p>The function <c>terminate_child/2</c> can be used for + children under <c>simple_one_for_one</c> supervisors by + giving the child's <c>pid()</c> as the second argument. If + instead the child specification identifier is used, + <c>terminate_child/2</c> will return + <c>{error,simple_one_for_one}</c>.</p> </item> </list> <p>To prevent a supervisor from getting into an infinite loop of @@ -311,24 +317,33 @@ child_spec() = {Id,StartFunc,Restart,Shutdown,Type,Modules} <type> <v>SupRef = Name | {Name,Node} | {global,Name} | pid()</v> <v> Name = Node = atom()</v> - <v>Id = term()</v> + <v>Id = pid() | term()</v> <v>Result = ok | {error,Error}</v> <v> Error = not_found | simple_one_for_one</v> </type> <desc> - <p>Tells the supervisor <c>SupRef</c> to terminate the child - process corresponding to the child specification identified - by <c>Id</c>. The process, if there is one, is terminated but - the child specification is kept by the supervisor. This means - that the child process may be later be restarted by - the supervisor. The child process can also be restarted - explicitly by calling <c>restart_child/2</c>. Use - <c>delete_child/2</c> to remove the child specification.</p> + <p>Tells the supervisor <c>SupRef</c> to terminate the given + child.</p> + <p>If the supervisor is not <c>simple_one_for_one</c>, + <c>Id</c> must be the child specification identifier. The + process, if there is one, is terminated but the child + specification is kept by the supervisor. The child process + may later be restarted by the supervisor. The child process + can also be restarted explicitly by calling + <c>restart_child/2</c>. Use <c>delete_child/2</c> to remove + the child specification.</p> + <p>If the supervisor is <c>simple_one_for_one</c>, <c>Id</c> + must be the child process' <c>pid()</c>. I the specified + process is alive, but is not a child of the given + supervisor, the function will return + <c>{error,not_found}</c>. If the child specification + identifier is given instead instead of a <c>pid()</c>, the + function will return <c>{error,simple_one_for_one}</c>.</p> + <p>If successful, the function returns <c>ok</c>. If there is + no child specification with the specified <c>Id</c>, the + function returns <c>{error,not_found}</c>.</p> <p>See <c>start_child/2</c> for a description of <c>SupRef</c>.</p> - <p>If successful, the function returns <c>ok</c>. If there is - no child specification with the specified <c>Id</c>, - the function returns <c>{error,not_found}</c>.</p> </desc> </func> <func> diff --git a/lib/stdlib/doc/src/supervisor_bridge.xml b/lib/stdlib/doc/src/supervisor_bridge.xml index b334f57caf..cbd0d9230b 100644 --- a/lib/stdlib/doc/src/supervisor_bridge.xml +++ b/lib/stdlib/doc/src/supervisor_bridge.xml @@ -5,7 +5,7 @@ <header> <copyright> <year>1996</year> - <year>2007</year> + <year>2011</year> <holder>Ericsson AB, All Rights Reserved</holder> </copyright> <legalnotice> diff --git a/lib/stdlib/doc/src/sys.xml b/lib/stdlib/doc/src/sys.xml index 8cbfb9387b..efa8922a9d 100644 --- a/lib/stdlib/doc/src/sys.xml +++ b/lib/stdlib/doc/src/sys.xml @@ -4,7 +4,7 @@ <erlref> <header> <copyright> - <year>1996</year><year>2009</year> + <year>1996</year><year>2011</year> <holder>Ericsson AB. All Rights Reserved.</holder> </copyright> <legalnotice> @@ -243,8 +243,8 @@ customise the value of <c>Misc</c> by exporting a <c>format_status/2</c> function that contributes module-specific information; - see <seealso marker="gen_server#format_status/2">gen_server:format_status/2</seealso> - and <seealso marker="gen_fsm#format_status/2">gen_fsm:format_status/2</seealso> + see <seealso marker="gen_server#Module:format_status/2">gen_server:format_status/2</seealso> + and <seealso marker="gen_fsm#Module:format_status/2">gen_fsm:format_status/2</seealso> for more details.</p> </desc> </func> diff --git a/lib/stdlib/doc/src/timer.xml b/lib/stdlib/doc/src/timer.xml index 1b34e71490..0baeff1db3 100644 --- a/lib/stdlib/doc/src/timer.xml +++ b/lib/stdlib/doc/src/timer.xml @@ -4,7 +4,7 @@ <erlref> <header> <copyright> - <year>1996</year><year>2009</year> + <year>1996</year><year>2011</year> <holder>Ericsson AB. All Rights Reserved.</holder> </copyright> <legalnotice> @@ -203,6 +203,7 @@ <func> <name>tc(Module, Function, Arguments) -> {Time, Value}</name> <name>tc(Fun, Arguments) -> {Time, Value}</name> + <name>tc(Fun) -> {Time, Value}</name> <fsummary>Measure the real time it takes to evaluate <c>apply(Module, Function, Arguments)</c> or <c>apply(Fun, Arguments)</c></fsummary> <type> @@ -218,7 +219,7 @@ <tag><c>tc/3</c></tag> <item> <p>Evaluates <c>apply(Module, Function, Arguments)</c> and measures - the elapsed real time as reported by <c>now/0</c>. + the elapsed real time as reported by <c>os:timestamp/0</c>. Returns <c>{Time, Value}</c>, where <c>Time</c> is the elapsed real time in <em>microseconds</em>, and <c>Value</c> is what is returned from the apply.</p> @@ -228,6 +229,11 @@ <p>Evaluates <c>apply(Fun, Arguments)</c>. Otherwise works like <c>tc/3</c>.</p> </item> + <tag><c>tc/1</c></tag> + <item> + <p>Evaluates <c>Fun()</c>. Otherwise works like <c>tc/2</c>.</p> + </item> + </taglist> </desc> </func> diff --git a/lib/stdlib/doc/src/unicode.xml b/lib/stdlib/doc/src/unicode.xml index 60edd8ade9..cb1cfa8ed0 100644 --- a/lib/stdlib/doc/src/unicode.xml +++ b/lib/stdlib/doc/src/unicode.xml @@ -5,7 +5,7 @@ <header> <copyright> <year>1996</year> - <year>2009</year> + <year>2011</year> <holder>Ericsson AB, All Rights Reserved</holder> </copyright> <legalnotice> @@ -40,7 +40,7 @@ <section> <title>DATA TYPES</title> - <marker id="charlist_definition"></marker> + <marker id="type-charlist"></marker> <code type="none"> unicode_binary() = binary() with characters encoded in UTF-8 coding standard unicode_char() = integer() representing valid unicode codepoint @@ -164,10 +164,16 @@ latin1_charlist() = [latin1_char() | latin1_binary() | latin1_charlist()] <item>Integers out of range - If <c>InEncoding</c> is <c>latin1</c>, an error occurs whenever an integer greater than 255 is found in the lists. If <c>InEncoding</c> is - of a Unicode type, error occurs whenever an integer greater than - <c>16#10FFFF</c> (the maximum unicode character) or in the - range <c>16#D800</c> to <c>16#DFFF</c> (invalid unicode - range) is found.</item> + of a Unicode type, an error occurs whenever an integer + <list type="bulleted"> + <item>greater than <c>16#10FFFF</c> + (the maximum unicode character),</item> + <item>in the range <c>16#D800</c> to <c>16#DFFF</c> + (invalid unicode range)</item> + <item>or equal to 16#FFFE or 16#FFFF (non characters)</item> + </list> + is found. + </item> <item>UTF encoding incorrect - If <c>InEncoding</c> is one of the UTF types, the bytes in any binaries have to be valid diff --git a/lib/stdlib/doc/src/unicode_usage.xml b/lib/stdlib/doc/src/unicode_usage.xml index c02ea3cbcb..416df1f02c 100644 --- a/lib/stdlib/doc/src/unicode_usage.xml +++ b/lib/stdlib/doc/src/unicode_usage.xml @@ -173,19 +173,19 @@ Eshell V5.7 (abort with ^G) <taglist> <tag>Mandatory Unicode file naming</tag> <item> -<p>Windows and, for most common uses, MacOSX enforces Unicode support for file names. All files created in the filesystem has names that can consistently be interpreted. In MacOSX, all file names are retrieved in UTF-8 encoding, while Windows have selected an approach where each system call handling file names has a special Unicode aware variant, giving much the same effect. There are no file names on these systems that are not Unicode file names, why the default behavior of the Erlang VM is to work in "Unicode file name translation mode", meaning that a file name can be given as a Unicode list and that will be automatically translated to the proper name encoding for the underlying operating and file system.</p> +<p>Windows and, for most common uses, MacOSX enforces Unicode support for file names. All files created in the filesystem have names that can consistently be interpreted. In MacOSX, all file names are retrieved in UTF-8 encoding, while Windows has selected an approach where each system call handling file names has a special Unicode aware variant, giving much the same effect. There are no file names on these systems that are not Unicode file names, why the default behavior of the Erlang VM is to work in "Unicode file name translation mode", meaning that a file name can be given as a Unicode list and that will be automatically translated to the proper name encoding for the underlying operating and file system.</p> <p>Doing i.e. a <c>file:list_dir/1</c> on one of these systems may return Unicode lists with codepoints beyond 255, depending on the content of the actual filesystem.</p> <p>As the feature is fairly new, you may still stumble upon non core applications that cannot handle being provided with file names containing characters with codepoints larger than 255, but the core Erlang system should have no problems with Unicode file names.</p> </item> <tag>Transparent file naming</tag> <item> <p>Most Unix operating systems have adopted a simpler approach, namely that Unicode file naming is not enforced, but by convention. Those systems usually use UTF-8 encoding for Unicode file names, but do not enforce it. On such a system, a file name containing characters having codepoints between 128 and 255 may be named either as plain ISO-latin-1 or using UTF-8 encoding. As no consistency is enforced, the Erlang VM can do no consistent translation of all file names. If the VM would automatically select encoding based on heuristics, one could get unexpected behavior on these systems, therefore file names not being encoded in UTF-8 are returned as "raw file names" if Unicode file naming support is turned on.</p> -<p>A raw file name is not a list, but a binary. Many non core applications still does not handle file names given as binaries, why such raw names are avoided by default. This means that systems having implemented Unicode file naming through transparent file systems and an UTF-8 convention, does not by default have Unicode file naming turned on. Explicitly turning Unicode file name handling on for these types of systems is considered experimental.</p> +<p>A raw file name is not a list, but a binary. Many non core applications still do not handle file names given as binaries, why such raw names are avoided by default. This means that systems having implemented Unicode file naming through transparent file systems and an UTF-8 convention, do not by default have Unicode file naming turned on. Explicitly turning Unicode file name handling on for these types of systems is considered experimental.</p> </item> </taglist> <p>The Unicode file naming support was introduced with OTP release R14B01. A VM operating in Unicode file mode can work with files having names in any language or character set (as long as it's supported by the underlying OS and file system). The Unicode character list is used to denote file or directory names and if the file system content is listed, you will also be able to get Unicode lists as return value. The support lies in the kernel and stdlib modules, why most applications (that does not explicitly require the file names to be in the ISO-latin-1 range) will benefit from the Unicode support without change.</p> -<p>On Operating systems with mandatory Unicode file names, this means that you more easily conform to the file names of other (non Erlang) applications, and you can also process file names that, at least on Windows, where completely inaccessible (due to having names that could not be represented in ISO-latin-1). Also you will avoid creating incomprehensible file names on MacOSX as the vfs layer of the OS will accept all your file names as UTF-8 and will not rewrite them.</p> +<p>On Operating systems with mandatory Unicode file names, this means that you more easily conform to the file names of other (non Erlang) applications, and you can also process file names that, at least on Windows, were completely inaccessible (due to having names that could not be represented in ISO-latin-1). Also you will avoid creating incomprehensible file names on MacOSX as the vfs layer of the OS will accept all your file names as UTF-8 and will not rewrite them.</p> <p>For most systems, turning on Unicode file name translation is no problem even if it uses transparent file naming. Very few systems have mixed file name encodings. A consistent UTF-8 named system will work perfectly in Unicode file name mode. It is still however considered experimental in R14B01. Unicode file name translation is turned on with the <c>+fnu</c> switch to the <c>erl</c> program. If the VM is started in Unicode file name translation mode, <c>file:native_name_encoding/0</c> will return the atom <c>utf8</c>.</p> @@ -197,10 +197,10 @@ Eshell V5.7 (abort with ^G) <section> <title>Notes about raw file names and automatic file name conversion</title> -<p>Raw file names is introduced together with Unicode file name support in erts-5.8.2 (OTP R14B01). The reason the "raw file names" is introduced in the system is to be able to consistently represent file names given in different encodings on the same system. Having the VM automatically translate a file name that is not in UTF-8 when to a list of Unicode characters might seem practical, but this would open up for both duplicate file names and other inconsistent behavior. Consider a directory containing a file named "bj�rn" in ISO-latin-1, while the Erlang VM is operating in Unicode file name mode (and therefore expecting UTF-8 file naming). The ISO-latin-1 name is not valid UTF-8 and one could be tempted to think that automatic conversion in for example <c>file:list_dir/1</c> is a good idea. But what would happen if we later tried to open the file and has the name as a Unicode list (magically converted from the ISO-latin-1 file name)? The VM will convert the file name given to UTF-8, as this is the encoding expected. Effectively this means trying to open the file named <<"bj�rn"/utf8>>. This file does not exist, and even if it existed it would not be the same file as the one that was listed. We could even create two files named "bj�rn", one named in the UTF-8 encoding and one not. If <c>file:list_dir/1</c> would automatically convert the ISO-latin-1 file name to a list, we would get two identical file names as the result. To avoid this, we need to differentiate between file names being properly encoded according to the Unicode file naming convention (i.e. UTF-8) and file names being invalid under the encoding. This is done by representing invalid encoding as "raw" file names, i.e. as binaries.</p> -<p>The core system of Erlang (kernel and stdlib) accept raw file names except for loadable drivers and executables invoked using <c>open_port({spawn, ...} ...)</c>. <c>open_port({spawn_executable, ...} ...)</c> however does accept them. As mentioned earlier, the arguments given in the option list to <c>open_port({spawn_executable, ...} ...)</c> undergo the same conversion as the file names, meaning that the executable will be provided with arguments in UTF-8 as well. This translation is avoided consistently with how the file names are treated, by giving the argument as a binary.</p> +<p>Raw file names is introduced together with Unicode file name support in erts-5.8.2 (OTP R14B01). The reason "raw file names" is introduced in the system is to be able to consistently represent file names given in different encodings on the same system. Having the VM automatically translate a file name that is not in UTF-8 to a list of Unicode characters might seem practical, but this would open up for both duplicate file names and other inconsistent behavior. Consider a directory containing a file named "bj�rn" in ISO-latin-1, while the Erlang VM is operating in Unicode file name mode (and therefore expecting UTF-8 file naming). The ISO-latin-1 name is not valid UTF-8 and one could be tempted to think that automatic conversion in for example <c>file:list_dir/1</c> is a good idea. But what would happen if we later tried to open the file and have the name as a Unicode list (magically converted from the ISO-latin-1 file name)? The VM will convert the file name given to UTF-8, as this is the encoding expected. Effectively this means trying to open the file named <<"bj�rn"/utf8>>. This file does not exist, and even if it existed it would not be the same file as the one that was listed. We could even create two files named "bj�rn", one named in the UTF-8 encoding and one not. If <c>file:list_dir/1</c> would automatically convert the ISO-latin-1 file name to a list, we would get two identical file names as the result. To avoid this, we need to differentiate between file names being properly encoded according to the Unicode file naming convention (i.e. UTF-8) and file names being invalid under the encoding. This is done by representing invalid encoding as "raw" file names, i.e. as binaries.</p> +<p>The core system of Erlang (kernel and stdlib) accepts raw file names except for loadable drivers and executables invoked using <c>open_port({spawn, ...} ...)</c>. <c>open_port({spawn_executable, ...} ...)</c> however does accept them. As mentioned earlier, the arguments given in the option list to <c>open_port({spawn_executable, ...} ...)</c> undergo the same conversion as the file names, meaning that the executable will be provided with arguments in UTF-8 as well. This translation is avoided consistently with how the file names are treated, by giving the argument as a binary.</p> <p>To force Unicode file name translation mode on systems where this is not the default is considered experimental in OTP R14B01 due to the raw file names possibly being a new experience to the programmer and that the non core applications of OTP are not tested for compliance with raw file names yet. Unicode file name translation is expected to be default in future releases.</p> -<p>If working with raw file names, one can still conform to the encoding convention of the Erlang VM by using the <c>file:native_name_encoding/0</c> function, which returns either the atom <c>latin1</c> or the atom <c>utf8</c> depending on the file name translation mode. On Linux, an VM started without explicitly stating the file name translation mode will default to <c>latin1</c> as the native file name encoding, why file names on the disk encoded as UTF-8 will be returned as a list of the names interpreted as ISO-latin-1. The "UTF-8 list" is not a practical type for displaying or operating on in Erlang, but it is backward compatible and usable in all functions requiring a file name. On Windows and MacOSX, the default behavior is that of file name translation, why the <c>file:native_name_encoding/0</c> by default returns <c>utf8</c> on those systems (the fact that Windows actually does not use UTF-8 on the file system level can safely be ignored by the Erlang programmer). The default behavior can be changed using the <c>+fnu</c> or <c>+fnl</c> options to the VM, see the <c>erl</c> command manual page.</p> +<p>If working with raw file names, one can still conform to the encoding convention of the Erlang VM by using the <c>file:native_name_encoding/0</c> function, which returns either the atom <c>latin1</c> or the atom <c>utf8</c> depending on the file name translation mode. On Linux, a VM started without explicitly stating the file name translation mode will default to <c>latin1</c> as the native file name encoding, why file names on the disk encoded as UTF-8 will be returned as a list of the names interpreted as ISO-latin-1. The "UTF-8 list" is not a practical type for displaying or operating on in Erlang, but it is backward compatible and usable in all functions requiring a file name. On Windows and MacOSX, the default behavior is that of file name translation, why the <c>file:native_name_encoding/0</c> by default returns <c>utf8</c> on those systems (the fact that Windows actually does not use UTF-8 on the file system level can safely be ignored by the Erlang programmer). The default behavior can be changed using the <c>+fnu</c> or <c>+fnl</c> options to the VM, see the <c>erl</c> command manual page.</p> <p>Even if you are operating without Unicode file naming translation automatically done by the VM, you can access and create files with names in UTF-8 encoding by using raw file names encoded as UTF-8. Enforcing the UTF-8 encoding regardless of the mode the Erlang VM is started in might, in some circumstances be a good idea, as the convention of using UTF-8 file names is spreading.</p> </section> <section> diff --git a/lib/stdlib/doc/src/zip.xml b/lib/stdlib/doc/src/zip.xml index 4d98a20206..529a70a23d 100644 --- a/lib/stdlib/doc/src/zip.xml +++ b/lib/stdlib/doc/src/zip.xml @@ -34,11 +34,11 @@ <module>zip</module> <modulesummary>Utility for reading and creating 'zip' archives.</modulesummary> <description> - <p>The <c>zip</c> module archives and extract files to and from a zip + <p>The <c>zip</c> module archives and extracts files to and from a zip archive. The zip format is specified by the "ZIP Appnote.txt" file available on PKWare's website www.pkware.com.</p> <p>The zip module supports zip archive versions up to 6.1. However, - password-protection and Zip64 is not supported.</p> + password-protection and Zip64 are not supported.</p> <p>By convention, the name of a zip file should end in "<c>.zip</c>". To abide to the convention, you'll need to add "<c>.zip</c>" yourself to the name.</p> @@ -52,7 +52,7 @@ <seealso marker="#unzip_2">unzip/2</seealso> function. (They are also available as <c>extract</c>.)</p> <p>To fold a function over all files in a zip archive, use the - <seealso marker="#foldl_3">foldl_3</seealso>.</p> + <seealso marker="#foldl_3">foldl_3</seealso> function.</p> <p>To return a list of the files in a zip archive, use the <seealso marker="#list_dir_1">list_dir/1</seealso> or the <seealso marker="#list_dir_2">list_dir/2</seealso> function. (They @@ -155,13 +155,13 @@ zip_file() </code> <p>Files will be compressed using the DEFLATE compression, as described in the Appnote.txt file. However, files will be stored without compression if they already are compressed. - The <c>zip/2</c> and <c>zip/3</c> checks the file extension + The <c>zip/2</c> and <c>zip/3</c> functions check the file extension to see whether the file should be stored without compression. Files with the following extensions are not compressed: <c>.Z</c>, <c>.zip</c>, <c>.zoo</c>, <c>.arc</c>, <c>.lzh</c>, <c>.arj</c>.</p> <p>It is possible to override the default behavior and - explicitly control what types of files that should be + explicitly control what types of files should be compressed by using the <c>{compress, What}</c> and <c>{uncompress, What}</c> options. It is possible to have several <c>compress</c> and <c>uncompress</c> options. In @@ -208,7 +208,7 @@ zip_file() </code> </item> <tag><c>{compress, What}</c></tag> <item> - <p>Controls what types of files that will be + <p>Controls what types of files will be compressed. It is by default set to <c>all</c>. The following values of <c>What</c> are allowed:</p> <taglist> @@ -228,7 +228,7 @@ zip_file() </code> </item> <tag><c>{uncompress, What}</c></tag> <item> - <p>Controls what types of files that will be uncompressed. It is by + <p>Controls what types of files will be uncompressed. It is by default set to <c>[".Z",".zip",".zoo",".arc",".lzh",".arj"]</c>. The following values of <c>What</c> are allowed:</p> <taglist> @@ -292,7 +292,7 @@ zip_file() </code> <p>By default, the <c>open/2</c> function will open the zip file in <c>raw</c> mode, which is faster but does not allow a remote (erlang) file server to be used. Adding <c>cooked</c> - to the mode list will override the default and open zip file + to the mode list will override the default and open the zip file without the <c>raw</c> option. The same goes for the files extracted.</p> </item> @@ -301,7 +301,7 @@ zip_file() </code> <p>By default, all existing files with the same name as file in the zip archive will be overwritten. With the <c>keep_old_files</c> option, the <c>unzip/2</c> function will not overwrite any existing - files. Not that even with the <c>memory</c> option given, which + files. Note that even with the <c>memory</c> option given, which means that no files will be overwritten, files existing will be excluded from the result.</p> </item> @@ -418,7 +418,7 @@ zip_file() </code> <p>By default, the <c>open/2</c> function will open the zip file in <c>raw</c> mode, which is faster but does not allow a remote (erlang) file server to be used. Adding <c>cooked</c> - to the mode list will override the default and open zip file + to the mode list will override the default and open the zip file without the <c>raw</c> option.</p> </item> </taglist> |