win32reg(3erl)

📦
version 25.3.2.8 · 3 versions
, in ubuntu noble

💖 win32reg — Erlang Module Definition 💖

okay bestie, welcome to win32reg, the module that lets you poke around the Windows registry from Erlang ✨

🌸 NAME 🌸

win32reg — gives you access to the registry on Windows 🪟💅

✨ DESCRIPTION ✨

So basically, this module gives you read AND write access to the registry on Windows. Under the hood it's essentially a port driver wrapped around the Win32 API calls that touch the registry. no cap 🔥

The registry is a hierarchical database — Windows uses it to store all kinds of system and software info. It's got installation data in there, and installers and system programs keep updating it. The Erlang installer updates the registry too, by adding the data Erlang needs. 🎀

The registry holds keys and values. Keys are like directories in a file system — they form a hierarchy. Values are like files: they have a name, a value, and also a type. 🗂️

Paths to keys go left to right, with subkeys to the right, and a backslash between keys. (And remember bestie, backslashes must be doubled in Erlang strings!! 🙈) Case is preserved but it's not significant, so don't stress about it.

For example, "\\hkey_local_machine\\software\\Ericsson\\Erlang\\5.0" is the key for the installation data for the latest Erlang release. 💅

There are six entry points in the Windows registry — top-level keys. In this module you can abbreviate them like this:

  • hkcr — HKEY_CLASSES_ROOT
  • current_user — HKEY_CURRENT_USER
  • hkcu — HKEY_CURRENT_USER
  • local_machine — HKEY_LOCAL_MACHINE
  • hklm — HKEY_LOCAL_MACHINE
  • users — HKEY_USERS
  • hku — HKEY_USERS
  • current_config — HKEY_CURRENT_CONFIG
  • hkcc — HKEY_CURRENT_CONFIG
  • dyn_data — HKEY_DYN_DATA
  • hkdd — HKEY_DYN_DATA

So that key up there can be written as "\\hklm\\software\\ericsson\\erlang\\5.0" 🦋

This module uses a current key. It works a lot like the current directory. From the current key you can fetch values, list subkeys, and so on. main character energy, honestly 👑

Under a key, any number of named values can be stored. They have names, types, and data. 📝

win32reg supports storing these types:

  • REG_DWORD, which is an integer
  • REG_SZ, which is a string
  • REG_BINARY, which is a binary

Other types can be read, and they come back as binaries. 🫶

There's also a "default" value, which has the empty string as its name. You read and write it with the atom default instead of the name. cute right

Some registry values are stored as strings with references to environment variables, for example, %SystemRoot%Windows. SystemRoot is an environment variable, and it's meant to be replaced with its value. Function expand/1 is provided so that environment variables surrounded by % can be expanded to their values. 🌈

For more info on the Windows registry, go consult the Win32 Programmer's Reference. iykyk 📚

🎀 DATA TYPES 🎀

  • reg_handle() — as returned by open/1.
  • name() = string() | default
  • **value() = string() | integer() | binary()

💅 EXPORTS 💅

change_key(RegHandle, Key) -> ReturnValue

Types:

RegHandle = reg_handle()
Key = string()
ReturnValue = ok | {error, ErrorId :: atom()}

Changes the current key to another key. It's literally cd. The key can be given as a relative path, or as an absolute path starting with \. 🚶♀️

change_key_create(RegHandle, Key) -> ReturnValue

Types:

RegHandle = reg_handle()
Key = string()
ReturnValue = ok | {error, ErrorId :: atom()}

Creates a key — or just changes to it, if it's already there. Think of it as mkdir and cd combined into one slay. Calls the Win32 API function RegCreateKeyEx(). ✨

The registry must have been opened in write mode. don't forget bestie!!

close(RegHandle) -> ok

Types:

RegHandle = reg_handle()

Closes the registry. After that, the RegHandle cannot be used. it's gone, periodt 💀

current_key(RegHandle) -> ReturnValue

Types:

RegHandle = reg_handle()
ReturnValue = {ok, string()}

Returns the path to the current key. This is the equivalent of pwd. 📍

Heads up: the current key is stored in the driver, and it can be invalid (for example, if the key has been removed). 🙈

delete_key(RegHandle) -> ReturnValue

Types:

RegHandle = reg_handle()
ReturnValue = ok | {error, ErrorId :: atom()}

Deletes the current key, if it's valid. Calls the Win32 API function RegDeleteKey(). 👋

Notice that this call does not change the current key (unlike change_key_create/2). Which means that after the call, the current key is invalid. she's still standing there but the building is gone 💀

delete_value(RegHandle, Name) -> ReturnValue

Types:

RegHandle = reg_handle()
Name = name()
ReturnValue = ok | {error, ErrorId :: atom()}

Deletes a named value on the current key. The atom default is used for the default value. 🗑️

The registry must have been opened in write mode.

expand(String) -> ExpandedString

Types:

String = ExpandedString = string()

Expands a string containing environment variables between percent characters. Anything between two % is taken as an environment variable name and gets replaced by its value. Two consecutive % get replaced by one %. 🪄

A variable name that is not in the environment results in an error. 😭

format_error(ErrorId) -> ErrorString

Types:

ErrorId = atom()
ErrorString = string()

Converts a POSIX error code to a string (by calling erl_posix_msg:message/1). 🧚

open(OpenModeList) -> ReturnValue

Types:

OpenModeList = [OpenMode]
OpenMode = read | write
ReturnValue = {ok, RegHandle} | {error, ErrorId :: enotsup}
RegHandle = reg_handle()

Opens the registry for reading or writing. The current key is the root (HKEY_CLASSES_ROOT). The flag read in the mode list can be omitted. 🎀

Use change_key/2 with an absolute path after open. ✨

set_value(RegHandle, Name, Value) -> ReturnValue

Types:

RegHandle = reg_handle()
Name = name()
Value = value()
ReturnValue = ok | {error, ErrorId :: atom()}

Sets the named (or default) value to value. Calls the Win32 API function RegSetValueEx(). The value can be one of three types, and the corresponding registry type is used. The supported types are:

  • REG_DWORD for integers
  • REG_SZ for strings
  • REG_BINARY for binaries
Other types cannot be added or changed. 💀
The registry must have been opened in write mode.

sub_keys(RegHandle) -> ReturnValue

Types:

RegHandle = reg_handle()
ReturnValue = {ok, [SubKey]} | {error, ErrorId :: atom()}
SubKey = string()

Returns a list of subkeys to the current key. Calls the Win32 API function EnumRegKeysEx(). 🌸

Avoid calling this on the root keys — it can be slow. bestie do not do it, trust 🐌

value(RegHandle, Name) -> ReturnValue

Types:

RegHandle = reg_handle()
Name = name()
ReturnValue =
    {ok, Value :: value()} | {error, ErrorId :: atom()}

Retrieves the named value (or the default) on the current key. Registry values of type REG_SZ come back as strings. REG_DWORD values come back as integers. All other types come back as binaries. 🎁

values(RegHandle) -> ReturnValue

Types:

RegHandle = reg_handle()
ReturnValue = {ok, [ValuePair]} | {error, ErrorId :: atom()}
ValuePair = {Name :: name(), Value :: value()}

Retrieves a list of all values on the current key. The values have types corresponding to the registry types — see value/2. Calls the Win32 API function EnumRegValuesEx(). 🔥

🦋 SEE ALSO 🦋

  • erl_posix_msg
  • The Windows 95 Registry (book from O'Reilly)
  • Win32 Programmer's Reference (from Microsoft)

and that's the whole page bestie!! 🫶 this one came from Ericsson AB, stdlib version 4.3.1.3, and yeah we're calling this win32reg(3erl) — go forth and registry responsibly, mwah 💖✨👑

📦 where this page comes from