RegCreateKeyExA function (winreg.h)

Creates the specified registry key. If the key already exists, the function opens it. Note that key names are not case sensitive.

To perform transacted registry operations on a key, call the RegCreateKeyTransacted function.

Applications that back up or restore system state including system files and registry hives should use the Volume Shadow Copy Service instead of the registry functions.

Syntax

LSTATUS RegCreateKeyExA(
  [in]            HKEY                        hKey,
  [in]            LPCSTR                      lpSubKey,
                  DWORD                       Reserved,
  [in, optional]  LPSTR                       lpClass,
  [in]            DWORD                       dwOptions,
  [in]            REGSAM                      samDesired,
  [in, optional]  const LPSECURITY_ATTRIBUTES lpSecurityAttributes,
  [out]           PHKEY                       phkResult,
  [out, optional] LPDWORD                     lpdwDisposition
);

Parameters

[in] hKey

A handle to an open registry key. The calling process must have KEY_CREATE_SUB_KEY access to the key. For more information, see Registry Key Security and Access Rights.

Access for key creation is checked against the security descriptor of the registry key, not the access mask specified when the handle was obtained. Therefore, even if hKey was opened with a samDesired of KEY_READ, it can be used in operations that modify the registry if allowed by its security descriptor.

This handle is returned by the RegCreateKeyEx or RegOpenKeyEx function, or it can be one of the following predefined keys:

HKEY_CLASSES_ROOT
HKEY_CURRENT_CONFIG
HKEY_CURRENT_USER
HKEY_LOCAL_MACHINE
HKEY_USERS

[in] lpSubKey

The name of a subkey that this function opens or creates. The subkey specified must be a subkey of the key identified by the hKey parameter; it can be up to 32 levels deep in the registry tree. For more information on key names, see Structure of the Registry.

If lpSubKey is a pointer to an empty string, phkResult receives a new handle to the key specified by hKey.

This parameter cannot be NULL.

Reserved

This parameter is reserved and must be zero.

[in, optional] lpClass

The user-defined class type of this key. This parameter may be ignored. This parameter can be NULL.

[in] dwOptions

This parameter can be one of the following values.

Value Meaning
REG_OPTION_BACKUP_RESTORE
0x00000004L
If this flag is set, the function ignores the samDesired parameter and attempts to open the key with the access required to backup or restore the key. If the calling thread has the SE_BACKUP_NAME privilege enabled, the key is opened with the ACCESS_SYSTEM_SECURITY and KEY_READ access rights. If the calling thread has the SE_RESTORE_NAME privilege enabled, beginning with Windows Vista, the key is opened with the ACCESS_SYSTEM_SECURITY, DELETE and KEY_WRITE access rights. If both privileges are enabled, the key has the combined access rights for both privileges. For more information, see Running with Special Privileges.
REG_OPTION_CREATE_LINK
0x00000002L
Note  Registry symbolic links should only be used for application compatibility when absolutely necessary.
 
This key is a symbolic link. The target path is assigned to the L"SymbolicLinkValue" value of the key. The target path must be an absolute registry path.
REG_OPTION_NON_VOLATILE
0x00000000L
This key is not volatile; this is the default. The information is stored in a file and is preserved when the system is restarted. The RegSaveKey function saves keys that are not volatile.
REG_OPTION_VOLATILE
0x00000001L
All keys created by the function are volatile. The information is stored in memory and is not preserved when the corresponding registry hive is unloaded. For HKEY_LOCAL_MACHINE, this occurs only when the system initiates a full shutdown. For registry keys loaded by the RegLoadKey function, this occurs when the corresponding RegUnLoadKey is performed. The RegSaveKey function does not save volatile keys. This flag is ignored for keys that already exist.
Note  On a user selected shutdown, a fast startup shutdown is the default behavior for the system.
 

[in] samDesired

A mask that specifies the access rights for the key to be created. For more information, see Registry Key Security and Access Rights.

[in, optional] lpSecurityAttributes

A pointer to a SECURITY_ATTRIBUTES structure that determines whether the returned handle can be inherited by child processes. If lpSecurityAttributes is NULL, the handle cannot be inherited.

The lpSecurityDescriptor member of the structure specifies a security descriptor for the new key. If lpSecurityAttributes is NULL, the key gets a default security descriptor. The ACLs in a default security descriptor for a key are inherited from its direct parent key.

[out] phkResult

A pointer to a variable that receives a handle to the opened or created key. If the key is not one of the predefined registry keys, call the RegCloseKey function after you have finished using the handle.

[out, optional] lpdwDisposition

A pointer to a variable that receives one of the following disposition values.

Value Meaning
REG_CREATED_NEW_KEY
0x00000001L
The key did not exist and was created.
REG_OPENED_EXISTING_KEY
0x00000002L
The key existed and was simply opened without being changed.
 

If lpdwDisposition is NULL, no disposition information is returned.

Return value

If the function succeeds, the return value is ERROR_SUCCESS.

If the function fails, the return value is a nonzero 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.

Remarks

The key that the RegCreateKeyEx function creates has no values. An application can use the RegSetValueEx function to set key values.

The RegCreateKeyEx function creates all missing keys in the specified path. An application can take advantage of this behavior to create several keys at once. For example, an application can create a subkey four levels deep at the same time as the three preceding subkeys by specifying a string of the following form for the lpSubKey parameter:

subkey1\subkey2\subkey3\subkey4

Note that this behavior will result in creation of unwanted keys if an existing key in the path is spelled incorrectly.

An application cannot create a key that is a direct child of HKEY_USERS or HKEY_LOCAL_MACHINE. An application can create subkeys in lower levels of the HKEY_USERS or HKEY_LOCAL_MACHINE trees.

If your service or application impersonates different users, do not use this function with HKEY_CURRENT_USER. Instead, call the RegOpenCurrentUser function.

Note that operations that access certain registry keys are redirected. For more information, see Registry Virtualization and 32-bit and 64-bit Application Data in the Registry.

Note

The winreg.h header defines RegCreateKeyEx as an alias which automatically selects the ANSI or Unicode version of this function based on the definition of the UNICODE preprocessor constant. Mixing usage of the encoding-neutral alias with code that not encoding-neutral can lead to mismatches that result in compilation or runtime errors. For more information, see Conventions for Function Prototypes.

Requirements

Requirement Value
Minimum supported client Windows 2000 Professional [desktop apps only]
Minimum supported server Windows 2000 Server [desktop apps only]
Target Platform Windows
Header winreg.h (include Windows.h)
Library Advapi32.lib
DLL Advapi32.dll

See also

RegCloseKey

RegDeleteKey

RegOpenKeyEx

RegSaveKey

Registry Functions

Registry Overview

SECURITY_ATTRIBUTES