Microsoft Docs

Your trusted source for Windows API documentation

RegCreateKeyEx function

RegCreateKeyEx function

Syntax

LONG RegCreateKeyEx(
  HKEY                      hKey,
  LPCSTR                    lpSubKey,
  DWORD                     Reserved,
  LPSTR                     lpClass,
  DWORD                     dwOptions,
  REGSAM                    samDesired,
  LPSECURITY_ATTRIBUTES     lpSecurityAttributes,
  PHKEY                     phkResult,
  LPDWORD                   lpdwDisposition
);

For a Unicode version of this function, see RegCreateKeyExW.

Parameters

Parameter Type Description
hKey [in] HKEY A handle to an open key. The key must have been opened with write access. If hKey specifies a key that is an alias, the underlying key must be opened with write access.

If the caller does not have KEY_WRITE access to the key identified by hKey, the function will fail.

A handle to the root of the registry or a handle to a registry key opened with the KEY_CREATE_SUB_KEY access right.

The value of hKey can be one of the following predefined reserved handles:
  • HKEY_CLASSES_ROOT
  • HKEY_CURRENT_USER
  • HKEY_LOCAL_MACHINE
  • HKEY_USERS
  • HKEY_CURRENT_CONFIG
lpSubKey [in] LPCSTR The name of the subkey to be created or opened. This member can be NULL.

The path can be a Unicode string.

This parameter cannot be a pointer to a string that is outside of the application's writable address space.
Reserved [in] DWORD This parameter is reserved and must be zero.
lpClass [out, optional] LPSTR A pointer to a null-terminated string that specifies the class of the new key. This parameter can be NULL.

If lpClass is NULL or an empty string, the class is not set.

If the function retrieves data for the class, it copies the data to the buffer pointed to by lpClass and returns the actual number of bytes copied to the buffer, not the number of bytes available.

If the buffer pointed to by lpClass is not large enough to hold the class, the function returns ERROR_MORE_DATA.

The class can be any user-defined string or one of the predefined system classes.
dwOptions [in] DWORD This parameter can be one of the following values:
  • REG_OPTION_NON_VOLATILE: The key is persistent. The key is stored in the registry file and is not flushed from memory until explicitly unloaded or the system is shut down. This is the default behavior.
  • REG_OPTION_VOLATILE: The key is volatile. The key is not stored in the registry file and is lost when the system is shut down.
samDesired [in] REGSAM A mask that specifies the desired access rights to the new key. For a list of values, see Registry Key Security and Access Rights.

If samDesired is specified as KEY_ALL_ACCESS, the caller must have KEY_CREATE_SUB_KEY access right.
lpSecurityAttributes [in, optional] LPSECURITY_ATTRIBUTES A pointer to a SECURITY_ATTRIBUTES structure that specifies the security attributes of the new key.

If this parameter is NULL, the new key is assigned a default security descriptor. The access control list (ACL) in the default security descriptor grants all access to the owner and members of the Administrators group, and has no access to the sysadmin group.
phkResult [out, optional] PHKEY A pointer to a variable that receives a handle to the newly created or opened key.

If phkResult is NULL, the handle is not returned. If the key is created, the handle is valid until it is closed by calling the RegCloseKey function.
lpdwDisposition [out, optional] LPDWORD A pointer to a variable that receives a value indicating whether the key was created or opened. This parameter can be NULL.

If this parameter is not NULL, lpdwDisposition can be one of the following values:
  • REG_CREATED_NEW_KEY: A new key was created.
  • REG_OPENED_EXISTING_KEY: The existing key was opened.

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 retrieve a system-defined message that describes the error.

Remarks

The RegCreateKeyEx function creates a new key or opens an existing key under the specified parent key.

If the key specified by lpSubKey does not exist, it is created.

If the key exists, RegCreateKeyEx opens it and returns a handle to it.

If lpdwDisposition is not NULL, the variable pointed to by lpdwDisposition receives either REG_CREATED_NEW_KEY or REG_OPENED_EXISTING_KEY.

The handle returned in phkResult is a handle to the opened key. It is valid until it is closed by calling the RegCloseKey function.

The samDesired parameter specifies the access rights for the new key. The caller must have write access to the parent key for the creation to succeed.

Requirements

SDK
Minimum supported client Windows 2000 Professional
Minimum supported server Windows 2000 Server
Header winreg.h (include Windows.h)
Library Advapi32.lib
DLL Advapi32.dll

See also