diff options
Diffstat (limited to 'lib/stdlib/doc/src/win32reg.xml')
| -rw-r--r-- | lib/stdlib/doc/src/win32reg.xml | 195 |
1 files changed, 117 insertions, 78 deletions
diff --git a/lib/stdlib/doc/src/win32reg.xml b/lib/stdlib/doc/src/win32reg.xml index 2a5a4a462d..f4a4fa1626 100644 --- a/lib/stdlib/doc/src/win32reg.xml +++ b/lib/stdlib/doc/src/win32reg.xml @@ -4,7 +4,7 @@ <erlref> <header> <copyright> - <year>2000</year><year>2013</year> + <year>2000</year><year>2016</year> <holder>Ericsson AB. All Rights Reserved.</holder> </copyright> <legalnotice> @@ -24,38 +24,39 @@ <title>win32reg</title> <prepared>Bjorn Gustavsson</prepared> - <responsible>NN</responsible> + <responsible></responsible> <docno></docno> - <approved>nobody</approved> - <checked>no</checked> + <approved></approved> + <checked></checked> <date>2000-08-10</date> <rev>PA1</rev> - <file>win32reg.sgml</file> + <file>win32reg.xml</file> </header> <module>win32reg</module> - <modulesummary>win32reg provides access to the registry on Windows</modulesummary> + <modulesummary>Provides access to the registry on Windows.</modulesummary> <description> - <p><c>win32reg</c> provides read and write access to the + <p>This module provides read and write access to the registry on Windows. It is essentially a port driver wrapped around the Win32 API calls for accessing the registry.</p> <p>The registry is a hierarchical database, used to store various system - and software information in Windows. It is available in Windows 95 and - Windows NT. It contains installation data, and is updated by installers + and software information in Windows. + It contains installation data, and is updated by installers and system programs. The Erlang installer updates the registry by adding data that Erlang needs.</p> <p>The registry contains keys and values. Keys are like the directories in a file system, they form a hierarchy. Values are like files, they have a name and a value, and also a type.</p> - <p>Paths to keys are left to right, with sub-keys to the right and backslash - between keys. (Remember that backslashes must be doubled in Erlang strings.) - Case is preserved but not significant. - Example: <c>"\\hkey_local_machine\\software\\Ericsson\\Erlang\\5.0"</c> is the key + <p>Paths to keys are left to right, with subkeys to the right and backslash + between keys. (Remember that backslashes must be doubled in Erlang + strings.) Case is preserved but not significant.</p> + <p>For example, + <c>"\\hkey_local_machine\\software\\Ericsson\\Erlang\\5.0"</c> is the key for the installation data for the latest Erlang release.</p> - <p>There are six entry points in the Windows registry, top level keys. They can be - abbreviated in the <c>win32reg</c> module as:</p> + <p>There are six entry points in the Windows registry, top-level keys. + They can be abbreviated in this module as follows:</p> <pre> -Abbrev. Registry key -======= ============ +Abbreviation Registry key +============ ============ hkcr HKEY_CLASSES_ROOT current_user HKEY_CURRENT_USER hkcu HKEY_CURRENT_USER @@ -67,29 +68,39 @@ current_config HKEY_CURRENT_CONFIG hkcc HKEY_CURRENT_CONFIG dyn_data HKEY_DYN_DATA hkdd HKEY_DYN_DATA</pre> - <p>The key above could be written as <c>"\\hklm\\software\\ericsson\\erlang\\5.0"</c>.</p> - <p>The <c>win32reg</c> module uses a current key. It works much like the - current directory. From the current key, values can be fetched, sub-keys + <p>The key above can be written as + <c>"\\hklm\\software\\ericsson\\erlang\\5.0"</c>.</p> + <p>This module uses a current key. It works much like the + current directory. From the current key, values can be fetched, subkeys can be listed, and so on.</p> - <p>Under a key, any number of named values can be stored. They have name, and + <p>Under a key, any number of named values can be stored. They have names, types, and data.</p> - <p>Currently, the <c>win32reg</c> module supports storing only the following - types: REG_DWORD, which is an - integer, REG_SZ which is a string and REG_BINARY which is a binary. - Other types can be read, and will be returned as binaries.</p> - <p>There is also a "default" value, which has the empty string as name. It is read and - written with the atom <c>default</c> instead of the name.</p> - <p>Some registry values are stored as strings with references to environment variables, - e.g. <c>"%SystemRoot%Windows"</c>. <c>SystemRoot</c> is an environment variable, and should be - replaced with its value. A function <c>expand/1</c> is provided, so that environment - variables surrounded in % can be expanded to their values.</p> - <p>For additional information on the Windows registry consult the Win32 + <p><c>win32reg</c> supports storing of the following types:</p> + <list type="bulleted"> + <item><c>REG_DWORD</c>, which is an integer</item> + <item><c>REG_SZ</c>, which is a string</item> + <item><c>REG_BINARY</c>, which is a binary</item> + </list> + <p>Other types can be read, and are returned as binaries.</p> + <p>There is also a "default" value, which has the empty string as name. It + is read and written with the atom <c>default</c> instead of the name.</p> + <p>Some registry values are stored as strings with references to environment + variables, for example, <c>%SystemRoot%Windows</c>. <c>SystemRoot</c> is + an environment variable, and is to be replaced with its value. Function + <seealso marker="#expand/1"><c>expand/1</c></seealso> is provided so that + environment variables surrounded by <c>%</c> can be expanded to their + values.</p> + <p>For more information on the Windows registry, see consult the Win32 Programmer's Reference.</p> </description> + <datatypes> <datatype> <name name="reg_handle"/> - <desc><p>As returned by <seealso marker="#open/1">open/1</seealso>.</p></desc> + <desc> + <p>As returned by + <seealso marker="#open/1"><c>open/1</c></seealso>.</p> + </desc> </datatype> <datatype> <name name="name"/> @@ -98,136 +109,164 @@ hkdd HKEY_DYN_DATA</pre> <name name="value"/> </datatype> </datatypes> + <funcs> <func> <name name="change_key" arity="2"/> - <fsummary>Move to a key in the registry</fsummary> + <fsummary>Move to a key in the registry.</fsummary> <desc> - <p>Changes the current key to another key. Works like cd. + <p>Changes the current key to another key. Works like <c>cd</c>. The key can be specified as a relative path or as an - absolute path, starting with \.</p> + absolute path, starting with <c>\.</c></p> </desc> </func> + <func> <name name="change_key_create" arity="2"/> - <fsummary>Move to a key, create it if it is not there</fsummary> + <fsummary>Move to a key, create it if it is not there.</fsummary> <desc> <p>Creates a key, or just changes to it, if it is already there. Works - like a combination of <c>mkdir</c> and <c>cd</c>. Calls the Win32 API function - <c>RegCreateKeyEx()</c>.</p> - <p>The registry must have been opened in write-mode.</p> + like a combination of <c>mkdir</c> and <c>cd</c>. + Calls the Win32 API function <c>RegCreateKeyEx()</c>.</p> + <p>The registry must have been opened in write mode.</p> </desc> </func> + <func> <name name="close" arity="1"/> <fsummary>Close the registry.</fsummary> <desc> - <p>Closes the registry. After that, the <c><anno>RegHandle</anno></c> cannot - be used.</p> + <p>Closes the registry. After that, the <c><anno>RegHandle</anno></c> + cannot be used.</p> </desc> </func> + <func> <name name="current_key" arity="1"/> <fsummary>Return the path to the current key.</fsummary> <desc> - <p>Returns the path to the current key. This is the equivalent of <c>pwd</c>.</p> - <p>Note that the current key is stored in the driver, and might be - invalid (e.g. if the key has been removed).</p> + <p>Returns the path to the current key. This is the equivalent of + <c>pwd</c>.</p> + <p>Notice that the current key is stored in the driver, and can be + invalid (for example, if the key has been removed).</p> </desc> </func> + <func> <name name="delete_key" arity="1"/> - <fsummary>Delete the current key</fsummary> + <fsummary>Delete the current key.</fsummary> <desc> <p>Deletes the current key, if it is valid. Calls the Win32 API - function <c>RegDeleteKey()</c>. Note that this call does not change the current key, - (unlike <c>change_key_create/2</c>.) This means that after the call, the - current key is invalid.</p> + function <c>RegDeleteKey()</c>. Notice that this call does not change + the current key (unlike + <seealso marker="#change_key_create/2"> + <c>change_key_create/2</c></seealso>). + This means that after the call, the current key is invalid.</p> </desc> </func> + <func> <name name="delete_value" arity="2"/> <fsummary>Delete the named value on the current key.</fsummary> <desc> <p>Deletes a named value on the current key. The atom <c>default</c> is - used for the the default value.</p> - <p>The registry must have been opened in write-mode.</p> + used for the default value.</p> + <p>The registry must have been opened in write mode.</p> </desc> </func> + <func> <name name="expand" arity="1"/> - <fsummary>Expand a string with environment variables</fsummary> + <fsummary>Expand a string with environment variables.</fsummary> <desc> <p>Expands a string containing environment variables between percent - characters. Anything between two % is taken for a environment - variable, and is replaced by the value. Two consecutive % is replaced - by one %.</p> - <p>A variable name that is not in the environment, will result in an error.</p> + characters. Anything between two <c>%</c> is taken for an environment + variable, and is replaced by the value. Two consecutive <c>%</c> are + replaced by one <c>%</c>.</p> + <p>A variable name that is not in the environment results in an + error.</p> </desc> </func> + <func> <name name="format_error" arity="1"/> - <fsummary>Convert an POSIX errorcode to a string</fsummary> + <fsummary>Convert a POSIX error code to a string.</fsummary> <desc> - <p>Convert an POSIX errorcode to a string (by calling <c>erl_posix_msg:message</c>).</p> + <p>Converts a POSIX error code to a string + (by calling <c>erl_posix_msg:message/1</c>).</p> </desc> </func> + <func> <name name="open" arity="1"/> - <fsummary>Open the registry for reading or writing</fsummary> + <fsummary>Open the registry for reading or writing.</fsummary> <desc> - <p>Opens the registry for reading or writing. The current key will be the root - (<c>HKEY_CLASSES_ROOT</c>). The <c>read</c> flag in the mode list can be omitted.</p> - <p>Use <c>change_key/2</c> with an absolute path after <c>open</c>.</p> + <p>Opens the registry for reading or writing. The current key is the + root (<c>HKEY_CLASSES_ROOT</c>). Flag <c>read</c> in the mode list + can be omitted.</p> + <p>Use <seealso marker="#change_key/2"><c>change_key/2</c></seealso> + with an absolute path after + <seealso marker="#open/1"><c>open</c></seealso>.</p> </desc> </func> + <func> <name name="set_value" arity="3"/> - <fsummary>Set value at the current registry key with specified name.</fsummary> + <fsummary>Set value at the current registry key with specified name. + </fsummary> <desc> - <p>Sets the named (or default) value to value. Calls the Win32 - API function <c>RegSetValueEx()</c>. The value can be of three types, and - the corresponding registry type will be used. Currently the types supported - are: <c>REG_DWORD</c> for integers, <c>REG_SZ</c> for strings and - <c>REG_BINARY</c> for binaries. Other types cannot currently be added - or changed.</p> - <p>The registry must have been opened in write-mode.</p> + <p>Sets the named (or default) value to <c>value</c>. Calls the Win32 + API function <c>RegSetValueEx()</c>. The value can be of three types, + and the corresponding registry type is used. The supported types + are the following:</p> + <list type="bulleted"> + <item><c>REG_DWORD</c> for integers</item> + <item><c>REG_SZ</c> for strings</item> + <item><c>REG_BINARY</c> for binaries</item> + </list> + <p>Other types cannot be added or changed.</p> + <p>The registry must have been opened in write mode.</p> </desc> </func> + <func> <name name="sub_keys" arity="1"/> <fsummary>Get subkeys to the current key.</fsummary> <desc> <p>Returns a list of subkeys to the current key. Calls the Win32 API function <c>EnumRegKeysEx()</c>.</p> - <p>Avoid calling this on the root keys, it can be slow.</p> + <p>Avoid calling this on the root keys, as it can be slow.</p> </desc> </func> + <func> <name name="value" arity="2"/> <fsummary>Get the named value on the current key.</fsummary> <desc> <p>Retrieves the named value (or default) on the current key. - Registry values of type <c>REG_SZ</c>, are returned as strings. Type <c>REG_DWORD</c> - values are returned as integers. All other types are returned as binaries.</p> + Registry values of type <c>REG_SZ</c> are returned as strings. + Type <c>REG_DWORD</c> values are returned as integers. All other + types are returned as binaries.</p> </desc> </func> + <func> <name name="values" arity="1"/> <fsummary>Get all values on the current key.</fsummary> <desc> <p>Retrieves a list of all values on the current key. The values - have types corresponding to the registry types, see <c>value</c>. + have types corresponding to the registry types, see + <seealso marker="#value/2"><c>value/2</c></seealso>. Calls the Win32 API function <c>EnumRegValuesEx()</c>.</p> </desc> </func> </funcs> <section> - <title>SEE ALSO</title> - <p>Win32 Programmer's Reference (from Microsoft)</p> - <p><c>erl_posix_msg</c></p> - <p>The Windows 95 Registry (book from O'Reilly)</p> + <title>See Also</title> + <p><c>erl_posix_msg</c>, + The Windows 95 Registry (book from O'Reilly), + Win32 Programmer's Reference (from Microsoft)</p> </section> </erlref> |