aboutsummaryrefslogtreecommitdiffstats
path: root/lib/stdlib/doc/src/win32reg.xml
diff options
context:
space:
mode:
Diffstat (limited to 'lib/stdlib/doc/src/win32reg.xml')
-rw-r--r--lib/stdlib/doc/src/win32reg.xml195
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>