registry(3tcl)

💖 registry — bestie edition 💖

okay so this is the registry page from the Tcl Bundled Packages manual set (that's the manual name, iykyk), and we're about to go into the Windows registry together. hold my hand. 🫶

---

✨ NAME ✨

registry — manipulate the Windows registry 💅

---

🌸 SYNOPSIS 🌸

package require registry 1.3

registry ?-mode? option keyName ?arg arg ...?

---

🦋 DESCRIPTION 🦋

okay so the registry package gives you a whole general set of operations for messing with the Windows registry. it implements the registry Tcl command. and ngl, this command is only supported on the Windows platform. periodt.

⚠️ warning bestie: use this command with caution, because a corrupted registry can leave your system in an unusable state. 😭 that is not a vibe. that is the opposite of a vibe.

KeyName is the name of a registry key. registry keys have to be one of these forms, no exceptions:

\\hostname\rootname\keypath

rootname\keypath

rootname

Hostname is the name of any valid Windows host that exports its registry. the rootname component must be one of:

• HKEY_LOCAL_MACHINE
• HKEY_USERS
• HKEY_CLASSES_ROOT
• HKEY_CURRENT_USER
• HKEY_CURRENT_CONFIG
• HKEY_PERFORMANCE_DATA
• HKEY_DYN_DATA

and the keypath can be one or more registry key names separated by backslash (\) characters. easy. iconic. 🎀

the optional -mode argument says which registry you're working with: when it's -32bit the 32-bit registry gets used, and when it's -64bit the 64-bit registry gets used. if you just... don't pass it, then the system's default registry is the subject of the operation you asked for. no cap.

Option is what you wanna do with the registry key name. any unique abbreviation for option is acceptable, so you can be lazy (affectionate). the valid options are:

• registry broadcast keyName ?-timeout milliseconds? — sends a broadcast message to the system and running programs so they get notified about certain updates. this is necessary to propagate changes to key registry keys like Environment. the timeout is how long, in milliseconds, to wait for applications to respond to the broadcast message. it defaults to 3000. here's the little example showing how to add a path to the global Environment and notify applications of the change without needing a logoff/logon step (and it assumes admin privileges, so bring your crown 👑):

set regPath [join {
    HKEY_LOCAL_MACHINE
    SYSTEM
    CurrentControlSet
    Control
    {Session Manager}
    Environment
} "\\"]
set curPath [registry get $regPath "Path"]
registry set $regPath "Path" "$curPath;$addPath"
registry broadcast "Environment"

• registry delete keyName ?valueName? — if the optional valueName argument is there, that specified value under keyName gets deleted from the registry. if valueName is omitted, then the specified key and any subkeys or values beneath it in the registry hierarchy get deleted (yes, all of it, the whole tree 💀). if the key could not be deleted then an error is generated. if the key didn't exist, the command has no effect — nothing happens, no drama.
• registry get keyName valueName — returns the data associated with the value valueName under the key keyName. if either the key or the value doesn't exist, an error is generated. for more details on the format of what you get back, see SUPPORTED TYPES below, bestie.
• registry keys keyName ?pattern? — if pattern isn't specified, returns a list of names of all the subkeys of keyName. if pattern is specified, only the names matching pattern come back. matching uses the same rules as for string match. and if the keyName you specified doesn't exist, an error is generated. 🙈
• registry set keyName ?valueName data ?type?? — if valueName isn't specified, it creates the key keyName if it doesn't already exist. if valueName is specified, it creates the key keyName and the value valueName if necessary. the contents of valueName get set to data with the type indicated by type. if type isn't specified, the type sz is assumed. for more details on the data and type arguments, see SUPPORTED TYPES below. ✨
• registry type keyName valueName — returns the type of the value valueName in the key keyName. for more info on the possible types, see SUPPORTED TYPES, below. (yes, again. it's a popular section. main character energy honestly.)
• registry values keyName ?pattern? — if pattern isn't specified, returns a list of names of all the values of keyName. if pattern is specified, only those names matching pattern are returned. matching is determined using the same rules as for string match. 🌈

---

💜 SUPPORTED TYPES 💜

each value under a key in the registry holds some data of a particular type, in a type-specific representation. the registry command converts between that internal representation and one that Tcl scripts can actually manipulate. in most cases the data is just handed back as a Tcl string. the type tells you the intended use for the data, but it does not actually change the representation. for some types though, the registry command returns the data in a different form to make it easier to manipulate. here are the types the registry command recognizes:

• binary — the registry value contains arbitrary binary data. the data is represented exactly in Tcl, including any embedded nulls. 🫶
• none — the registry value contains arbitrary binary data with no defined type. the data is represented exactly in Tcl, including any embedded nulls.
• sz — the registry value contains a null-terminated string. the data is represented in Tcl as a string. simple. slay.
• expand_sz — the registry value contains a null-terminated string that contains unexpanded references to environment variables in the normal Windows style (for example, “%PATH%”). the data is represented in Tcl as a string.
• dword — the registry value contains a little-endian 32-bit number. the data is represented in Tcl as a decimal string.
• dword_big_endian — the registry value contains a big-endian 32-bit number. the data is represented in Tcl as a decimal string.
• link — the registry value contains a symbolic link. the data is represented exactly in Tcl, including any embedded nulls. 🔗
• multi_sz — the registry value contains an array of null-terminated strings. the data is represented in Tcl as a list of strings.
• resource_list — the registry value contains a device-driver resource list. the data is represented exactly in Tcl, including any embedded nulls.

and on top of the symbolically named types listed above, unknown types get identified using a 32-bit integer that corresponds to the type code returned by the system interfaces. in that case, the data is represented exactly in Tcl, including any embedded nulls. (mystery type? still handled. we love a flexible queen. 👑)

---

🧚 PORTABILITY ISSUES 🧚

the registry command is only available on Windows. that's it, that's the section. 👑

---

⭐ EXAMPLE ⭐

print out how double-clicking on a Tcl script file will invoke a Tcl interpreter. here's how:

package require registry
set ext .tcl

# Read the type name
set type [registry get HKEY_CLASSES_ROOT\\$ext {}]
# Work out where to look for the command
set path HKEY_CLASSES_ROOT\\$type\\Shell\\Open\\command
# Read the command!
set command [registry get $path {}]

puts "$ext opens with $command"

look at that. clean. ate. 💅

---

🍓 KEYWORDS 🍓

registry

---

okay bestie that's the whole page, we did it 🎀 huge thanks to the registry package itself, sitting at version 1.1 — and this manual page came from the Tcl Bundled Packages set, filed under registry(3tcl). go forth and do not corrupt your registry, i am begging you. 💖✨🦋