RegUnloadKey function

Syntax

LONG RegUnloadKey(
  HKEY  hKey,
  LPCSTR lpSubKey
);

Parameters

Parameter	Description
hKey	A handle to an open registry key. The key is assumed to have been opened with the KEY_REMOTE_USER or KEY_ALL_ACCESS access right. This parameter can be a handle to a predefined registry key or a handle returned by the RegCreateKeyEx or RegOpenKeyEx function.
lpSubKey	The name of the subkey of the key specified by hKey that is to be unloaded. This parameter cannot be NULL. This subkey must be a volatile key. Volatile keys are not written to disk. Calls to RegSaveKey fail on volatile keys.

Return value

If the function succeeds, the return value is ERROR_SUCCESS.

If the function fails, the return value is a non-zero error code defined in Winerror.h. You can use the FormatMessage function with the FORMAT_MESSAGE_FROM_SYSTEM flag to get a generic description of the error.

Possible return values include:

• ERROR_SUCCESS: The operation was successful.
• ERROR_CANNOT_DELETE: Windows cannot delete some of the keys or entries.
• ERROR_INVALID_HANDLE: The handle specified is not valid.
• ERROR_SUCCESS_REBOOT_REQUIRED: The operation requires a reboot.

Remarks

The RegUnloadKey function unloads a previously loaded key and its subkeys. The key must be volatile.

For a key to be unloadable, it must have been loaded by RegLoadKey.

The handle hKey must be a handle to an open key that is a parent of the key to be unloaded. For example, to unload the "MyCompany" subkey, which is a subkey of HKEY_LOCAL_MACHINE\Software, you would open HKEY_LOCAL_MACHINE\Software and pass the handle to this key, along with the subkey name "MyCompany".

RegUnloadKey is the inverse of RegLoadKey.

The current user must have administrative privileges to unload a key.

This function does not affect the registry hive on disk. The data is only removed from memory.

Requirements

See also

• Registry Functions
• RegLoadKey
• RegCloseKey
• RegSaveKey