diff options
Diffstat (limited to 'lib/kernel/doc/src')
| -rw-r--r-- | lib/kernel/doc/src/code.xml | 2 | ||||
| -rw-r--r-- | lib/kernel/doc/src/disk_log.xml | 2 | ||||
| -rw-r--r-- | lib/kernel/doc/src/error_handler.xml | 2 | ||||
| -rw-r--r-- | lib/kernel/doc/src/file.xml | 76 | ||||
| -rw-r--r-- | lib/kernel/doc/src/gen_tcp.xml | 1 | ||||
| -rw-r--r-- | lib/kernel/doc/src/inet.xml | 65 | ||||
| -rw-r--r-- | lib/kernel/doc/src/notes.xml | 98 | ||||
| -rw-r--r-- | lib/kernel/doc/src/part_notes_history.xml | 2 | ||||
| -rw-r--r-- | lib/kernel/doc/src/rpc.xml | 2 | ||||
| -rw-r--r-- | lib/kernel/doc/src/user.xml | 2 |
10 files changed, 243 insertions, 9 deletions
diff --git a/lib/kernel/doc/src/code.xml b/lib/kernel/doc/src/code.xml index b8db509fa8..4b8f934df1 100644 --- a/lib/kernel/doc/src/code.xml +++ b/lib/kernel/doc/src/code.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> diff --git a/lib/kernel/doc/src/disk_log.xml b/lib/kernel/doc/src/disk_log.xml index 07c1844485..324d4264cf 100644 --- a/lib/kernel/doc/src/disk_log.xml +++ b/lib/kernel/doc/src/disk_log.xml @@ -5,7 +5,7 @@ <header> <copyright> <year>1997</year> - <year>2007</year> + <year>2011</year> <holder>Ericsson AB, All Rights Reserved</holder> </copyright> <legalnotice> diff --git a/lib/kernel/doc/src/error_handler.xml b/lib/kernel/doc/src/error_handler.xml index 94824688d1..7f78322472 100644 --- a/lib/kernel/doc/src/error_handler.xml +++ b/lib/kernel/doc/src/error_handler.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/kernel/doc/src/file.xml b/lib/kernel/doc/src/file.xml index 2044b074ee..36fce464c5 100644 --- a/lib/kernel/doc/src/file.xml +++ b/lib/kernel/doc/src/file.xml @@ -36,6 +36,61 @@ other Erlang processes to continue executing in parallel with the file operations. See the command line flag <c>+A</c> in <seealso marker="erts:erl">erl(1)</seealso>.</p> + + <p>The Erlang VM supports file names in Unicode to a limited + extent. Depending on how the VM is started (with the parameter + <c>+fnu</c> or <c>+fnl</c>), file names given can contain + characters > 255 and the VM system will convert file names + back and forth to the native file name encoding.</p> + + <p>The default behavior for Unicode character translation depends + on to what extent the underlying OS/filesystem enforces consistent + naming. On OSes where all file names are ensured to be in one or + another encoding, Unicode is the default (currently this holds for + Windows and MacOSX). On OSes with completely transparent file + naming (i.e. all Unixes except MacOSX), ISO-latin-1 file naming is + the default. The reason for the ISO-latin-1 default is that + file names are not guaranteed to be possible to interpret according to + the Unicode encoding expected (i.e. UTF-8), and file names that + cannot be decoded will only be accessible by using "raw + file names", in other word file names given as binaries.</p> + + <p>As file names are traditionally not binaries in Erlang, + applications that need to handle raw file names need to be + converted, why the Unicode mode for file names is not default on + systems having completely transparent file naming.</p> + + <note>As of R14B01, the most basic file handling modules + (<c>file</c>, <c>prim_file</c>, <c>filelib</c> and + <c>filename</c>) accept raw file names, but the rest of OTP is not + guaranteed to handle them, why Unicode file naming on systems + where it is not default is still considered experimental.</note> + + <p>Raw file names is a new feature in OTP R14B01, which allows the + user to supply completely uninterpreted file names to the + underlying OS/filesystem. They are supplied as binaries, where it + is up to the user to supply a correct encoding for the + environment. The function <c>file:native_name_encoding()</c> can + be used to check what encoding the VM is working in. If the + function returns <c>latin1</c> file names are not in any way + converted to Unicode, if it is <c>utf8</c>, raw file names should + be encoded as UTF-8 if they are to follow the convention of the VM + (and usually the convention of the OS as well). Using raw + file names is useful if you have a filesystem with inconsistent + file naming, where some files are named in UTF-8 encoding while + others are not. A file:list_dir on such mixed file name systems + when the VM is in Unicode file name mode might return file names as + raw binaries as they cannot be interpreted as Unicode + file names. Raw file names can also be used to give UTF-8 encoded + file names even though the VM is not started in Unicode file name + translation mode.</p> + + <p>Note that on Windows, <c>file:native_name_encoding()</c> + returns <c>utf8</c> per default, which is the format for raw + file names even on Windows, although the underlying OS specific + code works in a limited version of little endian UTF16. As far as + the Erlang programmer is concerned, Windows native Unicode format + is UTF-8...</p> </description> <section> @@ -47,8 +102,14 @@ iodata() = iolist() | binary() io_device() as returned by file:open/2, a process handling IO protocols -name() = string() | atom() | DeepList +name() = 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. + RawFilename is a filename not subject to Unicode translation, meaning that it + can contain characters not conforming to the Unicode encoding expected from the + filesystem (i.e. non-UTF-8 characters although the VM is started in Unicode + filename mode). posix() an atom which is named from the POSIX error codes used in @@ -598,13 +659,24 @@ f.txt: {person, "kalle", 25}. </desc> </func> <func> + <name>native_name_encoding() -> latin1 | utf8</name> + <fsummary>Return the VM's configured filename encoding.</fsummary> + <desc> + <p>This function returns the configured default file name encoding to use for raw file names. Generally an application supplying file names raw (as binaries), should obey the character encoding returned by this function.</p> + <p>By default, the VM uses ISO-latin-1 file name encoding on filesystems and/or OSes that use completely transparent file naming. This includes all Unix versions except MacOSX, where the vfs layer enforces UTF-8 file naming. By giving the experimental option <c>+fnu</c> when starting Erlang, UTF-8 translation of file names can be turned on even for those systems. If Unicode file name translation is in effect, the system behaves as usual as long as file names conform to the encoding, but will return file names that are not properly encoded in UTF-8 as raw file names (i.e. binaries).</p> + <p>On Windows, this function also returns <c>utf8</c> by default. The OS uses a pure Unicode naming scheme and file names are always possible to interpret as valid Unicode. The fact that the underlying Windows OS actually encodes file names using little endian UTF-16 can be ignored by the Erlang programmer. Windows and MacOSX are the only operating systems where the VM operates in Unicode file name mode by default.</p> + </desc> + </func> + <func> <name>open(Filename, Modes) -> {ok, IoDevice} | {error, Reason}</name> <fsummary>Open a file</fsummary> <type> <v>Filename = name()</v> <v>Modes = [Mode]</v> - <v> Mode = read | write | append | exclusive | raw | binary | {delayed_write, Size, Delay} | delayed_write | {read_ahead, Size} | read_ahead | compressed</v> + <v> Mode = read | write | append | exclusive | raw | binary | {delayed_write, Size, Delay} | delayed_write | {read_ahead, Size} | read_ahead | compressed | {encoding, Encoding}</v> <v> Size = Delay = int()</v> + <v> Encoding = latin1 | unicode | utf8 | utf16 | {utf16, Endian} | utf32 | {utf32, Endian}</v> + <v> Endian = big | little</v> <v>IoDevice = io_device()</v> <v>Reason = ext_posix() | system_limit</v> </type> diff --git a/lib/kernel/doc/src/gen_tcp.xml b/lib/kernel/doc/src/gen_tcp.xml index 8e7192a496..aa171c77c2 100644 --- a/lib/kernel/doc/src/gen_tcp.xml +++ b/lib/kernel/doc/src/gen_tcp.xml @@ -74,6 +74,7 @@ posix() socket() as returned by accept/1,2 and connect/3,4</code> + <marker id="connect"></marker> </section> <funcs> <func> diff --git a/lib/kernel/doc/src/inet.xml b/lib/kernel/doc/src/inet.xml index 2ae230152c..f05a224f33 100644 --- a/lib/kernel/doc/src/inet.xml +++ b/lib/kernel/doc/src/inet.xml @@ -220,6 +220,69 @@ fe80::204:acff:fe17:bf38 <p>Returns the local hostname. Will never fail.</p> </desc> </func> + + <func> + <name>getifaddrs() -> {ok,Iflist} | {error,posix}</name> + <fsummary>Return a list of interfaces and their addresses</fsummary> + <type> + <v>Iflist = {Ifname,[Ifopt]}</v> + <v>Ifname = string()</v> + <v>Ifopt = {flag,[Flag]} | {addr,Addr} | {netmask,Netmask} + | {broadaddr,Broadaddr} | {dstaddr,Dstaddr} + | {hwaddr,Hwaddr}</v> + <v>Flag = up | broadcast | loopback | pointtopoint + | running | multicast</v> + <v>Addr = Netmask = Broadadddr = Dstaddr = ip_address()</v> + <v>Hwaddr = [byte()]</v> + </type> + </func> + <desc> + <p> + Returns a list of 2-tuples containing interface names and the + interface's addresses. <c>Ifname</c> is a Unicode string. + <c>Hwaddr</c> is hardware dependent, e.g on Ethernet interfaces + it is the 6-byte Ethernet address (MAC address (EUI-48 address)). + </p> + <p> + The <c>{addr,Addr}</c>, <c>{netmask,_}</c> and <c>{broadaddr,_}</c> + tuples are repeated in the result list iff the interface has multiple + addresses. If you come across an interface that has + multiple <c>{flag,_}</c> or <c>{hwaddr,_}</c> tuples you have + a really strange interface or possibly a bug in this function. + The <c>{flag,_}</c> tuple is mandatory, all other optional. + </p> + <p> + Do not rely too much on the order of <c>Flag</c> atoms or + <c>Ifopt</c> tuples. There are some rules, though: + <list> + <item> + Immediately after <c>{addr,_}</c> follows <c>{netmask,_}</c> + </item> + <item> + Immediately thereafter follows <c>{broadaddr,_}</c> if + the <c>broadcast</c> flag is <em>not</em> set and the + <c>pointtopoint</c>flag <em>is</em> set. + </item> + <item> + Any <c>{netmask,_}</c>, <c>{broadaddr,_}</c> or + <c>{dstaddr,_}</c> tuples that follow an <c>{addr,_}</c> + tuple concerns that address. + </item> + </list> + </p> + <p> + The <c>{hwaddr,_}</c> tuple is not returned on Solaris since the + hardware address historically belongs to the link layer and only + the superuser can read such addresses. + </p> + <p> + On Windows, the data is fetched from quite different OS API + functions, so the <c>Netmask</c> and <c>Broadaddr</c> + values may be calculated, just as some <c>Flag</c> values. + You have been warned. Report flagrant bugs. + </p> + </desc> + <func> <name>getopts(Socket, Options) -> {ok, OptionValues} | {error, posix()}</name> <fsummary>Get one or more options for a socket</fsummary> @@ -369,7 +432,7 @@ fe80::204:acff:fe17:bf38 </desc> </func> <func> - <name>port(Socket) -> {ok, Port}</name> + <name>port(Socket) -> {ok, Port} | {error, any()}</name> <fsummary>Return the local port number for a socket</fsummary> <type> <v>Socket = socket()</v> diff --git a/lib/kernel/doc/src/notes.xml b/lib/kernel/doc/src/notes.xml index edd6ea52b0..065b24c53d 100644 --- a/lib/kernel/doc/src/notes.xml +++ b/lib/kernel/doc/src/notes.xml @@ -30,6 +30,104 @@ </header> <p>This document describes the changes made to the Kernel application.</p> +<section><title>Kernel 2.14.3</title> + + <section><title>Fixed Bugs and Malfunctions</title> + <list> + <item> + <p> + <c>os:find_executable/{1,2}</c> will no longer return the + path of a directory that happens to be in the PATH.</p> + <p> + Own Id: OTP-8983 Aux Id: seq11749 </p> + </item> + <item> + <p> + Fix -spec for file:write_file/3</p> + <p> + Change type for second parameter from binary() to + iodata(), since the function explicitly takes steps to + accept lists as well as binaries. (thanks to Magnus + Henoch).</p> + <p> + Own Id: OTP-9067</p> + </item> + <item> + <p> + Sanitize the specs of the code module</p> + <p> + After the addition of unicode_binary() to the + file:filename() type, dialyzer started complaining about + erroneous or incomplete specs in some functions of the + 'code' module. The culprit was hard-coded information in + erl_bif_types for functions of this module, which were + not updated. Since these functions have proper specs + these days and code duplication (pun intended) is never a + good idea, their type information was removed from + erl_bif_types.</p> + <p> + While doing this, some erroneous comments were fixed in + the code module and also made sure that the code now runs + without dialyzer warnings even when the + -Wunmatched_returns option is used.</p> + <p> + Some cleanups were applied to erl_bif_types too.</p> + <p> + Own Id: OTP-9100</p> + </item> + <item> + <p> + - Add spec for function that does not return - Strenghen + spec - Introduce types to avoid duplication in specs - + Add specs for functions that do not return - Add specs + for behaviour callbacks - Simplify two specs</p> + <p> + Own Id: OTP-9127</p> + </item> + </list> + </section> + +</section> + +<section><title>Kernel 2.14.2</title> + + <section><title>Improvements and New Features</title> + <list> + <item> + <p> + The Erlang VM now supports Unicode filenames. The feature + is turned on by default on systems where Unicode + filenames are mandatory (Windows and MacOSX), but can be + enabled on other systems with the '+fnu' emulator option. + Enabling the Unicode filename feature on systems where it + is not default is however considered experimental and not + to be used for production. Together with the Unicode file + name support, the concept of "raw filenames" is + introduced, which means filenames provided without + implicit unicode encoding translation. Raw filenames are + provided as binaries, not lists. For further information, + see stdlib users guide and the chapter about using + Unicode in Erlang. Also see the file module manual page.</p> + <p> + *** POTENTIAL INCOMPATIBILITY ***</p> + <p> + Own Id: OTP-8887</p> + </item> + <item> + <p> + There is now a new function inet:getifaddrs/0 modeled + after C library function getifaddrs() on BSD and LInux + that reports existing interfaces and their addresses on + the host. This replaces the undocumented and unsupported + inet:getiflist/0 and inet:ifget/2.</p> + <p> + Own Id: OTP-8926</p> + </item> + </list> + </section> + +</section> + <section><title>Kernel 2.14.1.1</title> <section><title>Fixed Bugs and Malfunctions</title> diff --git a/lib/kernel/doc/src/part_notes_history.xml b/lib/kernel/doc/src/part_notes_history.xml index 07c7e4abea..a73cc911b8 100644 --- a/lib/kernel/doc/src/part_notes_history.xml +++ b/lib/kernel/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/kernel/doc/src/rpc.xml b/lib/kernel/doc/src/rpc.xml index 86c6ea9178..2b81de170d 100644 --- a/lib/kernel/doc/src/rpc.xml +++ b/lib/kernel/doc/src/rpc.xml @@ -454,7 +454,7 @@ </desc> </func> <func> - <name>pmap({Module, Function}, ExtraArgs, List2) -> List1</name> + <name>pmap({Module, Function}, ExtraArgs, List1) -> List2</name> <fsummary>Parallell evaluation of mapping a function over a list </fsummary> <type> <v>Module = Function = atom()</v> diff --git a/lib/kernel/doc/src/user.xml b/lib/kernel/doc/src/user.xml index d9de2f4b04..4d0f044321 100644 --- a/lib/kernel/doc/src/user.xml +++ b/lib/kernel/doc/src/user.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> |