Duplicates an object handle.

Syntax

BOOL WINAPI DuplicateHandle(
  __in   HANDLE hSourceProcessHandle,
  __in   HANDLE hSourceHandle,
  __in   HANDLE hTargetProcessHandle,
  __out  LPHANDLE lpTargetHandle,
  __in   DWORD dwDesiredAccess,
  __in   BOOL bInheritHandle,
  __in   DWORD dwOptions
);

Parameters

hSourceProcessHandle [in]

A handle to the process with the handle to be duplicated.

The handle must have the PROCESS_DUP_HANDLE access right. For more information, see Process Security and Access Rights.

hSourceHandle [in]

The handle to be duplicated. This is an open object handle that is valid in the context of the source process. For a list of objects whose handles can be duplicated, see the following Remarks section.

hTargetProcessHandle [in]

A handle to the process that is to receive the duplicated handle. The handle must have the PROCESS_DUP_HANDLE access right.

lpTargetHandle [out]

A pointer to a variable that receives the duplicate handle. This handle value is valid in the context of the target process.

If hSourceHandle is a pseudo handle returned by GetCurrentProcess or GetCurrentThread, DuplicateHandle converts it to a real handle to a process or thread, respectively.

If lpTargetHandle is NULL, the function duplicates the handle, but does not return the duplicate handle value to the caller. This behavior exists only for backward compatibility with previous versions of this function. You should not use this feature, as you will lose system resources until the target process terminates.

dwDesiredAccess [in]

The access requested for the new handle. For the flags that can be specified for each object type, see the following Remarks section.

This parameter is ignored if the dwOptions parameter specifies the DUPLICATE_SAME_ACCESS flag. Otherwise, the flags that can be specified depend on the type of object whose handle is to be duplicated.

bInheritHandle [in]

A variable that indicates whether the handle is inheritable. If TRUE, the duplicate handle can be inherited by new processes created by the target process. If FALSE, the new handle cannot be inherited.

dwOptions [in]

Optional actions. This parameter can be zero, or any combination of the following values.

Value	Meaning
DUPLICATE_CLOSE_SOURCE 0x00000001	Closes the source handle. This occurs regardless of any error status returned.
DUPLICATE_SAME_ACCESS 0x00000002	Ignores the dwDesiredAccess parameter. The duplicate handle has the same access as the source handle.

 

Return Value

If the function succeeds, the return value is nonzero.

If the function fails, the return value is zero. To get extended error information, call GetLastError.

Remarks

The duplicate handle refers to the same object as the original handle. Therefore, any changes to the object are reflected through both handles. For example, if you duplicate a file handle, the current file position is always the same for both handles. For file handles to have different file positions, use the CreateFile function to create file handles that share access to the same file.

DuplicateHandle can be called by either the source process or the target process (or a process that is both the source and target process). For example, a process can use DuplicateHandle to create a noninheritable duplicate of an inheritable handle, or a handle with different access than the original handle.

The source process uses the GetCurrentProcess function to get a handle to itself. This handle is a pseudo handle, but DuplicateHandle converts it to a real process handle. To get the target process handle, it may be necessary to use some form of interprocess communication (for example, a named pipe or shared memory) to communicate the process identifier to the source process. The source process can use this identifier in the OpenProcess function to obtain a handle to the target process.

If the process that calls DuplicateHandle is not also the target process, the source process must use interprocess communication to pass the value of the duplicate handle to the target process.

DuplicateHandle can be used to duplicate a handle between a 32-bit process and a 64-bit process. The resulting handle is appropriately sized to work in the target process. For more information, see Process Interoperability.

DuplicateHandle can duplicate handles to the following types of objects.

You should not use DuplicateHandle to duplicate handles to the following objects:

• I/O completion ports. No error is returned, but the duplicate handle cannot be used.
• Sockets. No error is returned, but the duplicate handle may not be recognized by Winsock at the target process. Also, using DuplicateHandle interferes with internal reference counting on the underlying object. To duplicate a socket handle, use the WSADuplicateSocket function.

The dwDesiredAccess parameter specifies the new handle's access rights. All objects support the standard access rights. Objects may also support additional access rights depending on the object type. For more information, see the following topics:

• Desktop Security and Access Rights
• File Security and Access Rights
• File-Mapping Security and Access Rights
• Job Object Security and Access Rights
• Process Security and Access Rights
• Registry Key Security and Access Rights
• Synchronization Object Security and Access Rights
• Thread Security and Access Rights
• Window-Station Security and Access Rights

In some cases, the new handle can have more access rights than the original handle. However, in other cases, DuplicateHandle cannot create a handle with more access rights than the original. For example, a file handle created with the GENERIC_READ access right cannot be duplicated so that it has both the GENERIC_READ and GENERIC_WRITE access right.

Normally the target process closes a duplicated handle when that process is finished using the handle. To close a duplicated handle from the source process, call DuplicateHandle with the following parameters:

• Set hSourceProcessHandle to the target process from the DuplicateHandle call that created the handle.
• Set hSourceHandle to the duplicated handle to close.
• Set lpTargetHandle to NULL.
• Set dwOptions to DUPLICATE_CLOSE_SOURCE.

Examples

The following example creates a mutex, duplicates a handle to the mutex, and passes it to another thread. Duplicating the handle ensures that the reference count is increased so that the mutex object will not be destroyed until both threads have closed the handle.

#include <windows.h>

DWORD CALLBACK ThreadProc(PVOID pvParam);

int main()
{
    HANDLE hMutex = CreateMutex(NULL, FALSE, NULL);
    HANDLE hMutexDup, hThread;
    DWORD dwThreadId;

    DuplicateHandle(GetCurrentProcess(), 
                    hMutex, 
                    GetCurrentProcess(),
                    &hMutexDup, 
                    0,
                    FALSE,
                    DUPLICATE_SAME_ACCESS);

    hThread = CreateThread(NULL, 0, ThreadProc, 
        (LPVOID) hMutexDup, 0, &dwThreadId);

    // Perform work here, closing the handle when finished with the
    // mutex. If the reference count is zero, the object is destroyed.
    CloseHandle(hMutex);

    // Wait for the worker thread to terminate and clean up.
    WaitForSingleObject(hThread, INFINITE);
    CloseHandle(hThread);
    return 0;
}

DWORD CALLBACK ThreadProc(PVOID pvParam)
{
    HANDLE hMutex = (HANDLE)pvParam;

    // Perform work here, closing the handle when finished with the
    // mutex. If the reference count is zero, the object is destroyed.
    CloseHandle(hMutex);
    return 0;
}

Requirements

See Also

CloseHandle

Handle and Object Functions

Handle Inheritance

Send comments about this topic to Microsoft

Build date: 11/19/2009