CreateProcess (Compact 2013)

  • Article

3/28/2014

This function is used to run a new program. It creates a new process and its primary thread. The new process runs the specified executable file.

Syntax

BOOL CreateProcess(
  LPCWSTR pszImageName,
  LPCWSTR pszCmdLine,
  LPSECURITY_ATTRIBUTES psaProcess,
  LPSECURITY_ATTRIBUTES psaThread,
  BOOL fInheritHandles,
  DWORD fdwCreate,
  LPVOID pvEnvironment,
  LPWSTR pszCurDir,
  LPSTARTUPINFOW psiStartInfo,
  LPPROCESS_INFORMATION pProcInfo
);

Parameters

  • pszImageName
    [in] Pointer to a null-terminated string that specifies the module to execute.

    The string can specify the full path and filename of the module to execute or it can specify a partial path and filename.

    The lpszImageName parameter must be non-NULL and must include the module name.

  • pszCmdLine
    [in, out] Pointer to a null-terminated string that specifies the command line to execute.

    The system adds a null character to the command line, trimming the string if necessary, to indicate which file was used.

    The lpszCmdLine parameter can be NULL. In that case, the function uses the string pointed to by lpszImageName as the command line.

    If lpszImageName and lpszCmdLine are non-NULL, *lpszImageName specifies the module to execute, and *lpszCmdLine specifies the command line.

    C runtime processes can use the argc and argv arguments.

    If the filename does not contain an EXE extension, an EXE extension is appended.

    If the filename ends in a period (.) with no extension, or if the filename contains a path, .EXE is not appended.

  • psaProcess
    [in] Not supported; set to NULL.
  • psaThread
    [in] Not supported; set to NULL.
  • fInheritHandles
    [in] Not supported; set to FALSE.

  • fdwCreate
    [in] Specifies additional flags that control the priority and the creation of the process.

    The following table shows the creation flags that can be specified in any combination, except as noted.

    Value

    Description

    CREATE_DEFAULT_ERROR_MODE

    Not supported.

    CREATE_NEW_CONSOLE

    The new process has a new console, instead of inheriting the parent's console.

    CREATE_NEW_PROCESS_GROUP

    Not supported.

    CREATE_SEPARATE_WOW_VDM

    Not supported.

    CREATE_SHARED_WOW_VDM

    Not supported.

    CREATE_SUSPENDED

    The primary thread of the new process is created in a suspended state, and does not run until the ResumeThread function is called.

    CREATE_UNICODE_ENVIRONMENT

    Not supported.

    DEBUG_PROCESS

    If this flag is set, the calling process is treated as a debugger, and the new process is a process being debugged. Child processes of the new process are also debugged.

    The system notifies the debugger of all debug events that occur in the process being debugged.

    If you create a process with this flag set, only the calling thread (the thread that called CreateProcess) can call the WaitForDebugEvent function.

    DEBUG_ONLY_THIS_PROCESS

    If this flag is set, the calling process is treated as a debugger, and the new process is a process being debugged. No child processes of the new process are debugged.

    The system notifies the debugger of all debug events that occur in the process being debugged.

    DETACHED_PROCESS

    Not supported.

    INHERIT_CALLER_PRIORITY

    If this flag is set, the new process inherits the priority of the creator process.

    Windows Embedded Compact does not support the concept of a priority class. The priority of a thread is the only parameter that determines a thread's scheduling priority.

  • pvEnvironment
    [in] Not supported; set to NULL.
  • pszCurDir
    [in] Not supported; set to NULL.
  • psiStartInfo
    [in] Not supported; set to NULL.

  • pProcInfo
    [out] Pointer to a PROCESS_INFORMATION structure that receives identification information about the new process. Callers that do not need the process and thread handles returned in the PROCESS_INFORMATION structure can simply pass NULL for pProcInfo.

    When using the CreateProcess function, the process and thread handles returned in the PROCESS_INFORMATION structure can only be used for signaling purposes such as waiting, and for querying the exit code of the process or thread with the GetExitCodeProcess function.

    Functions such as ReadProcessMemory, WriteProcessMemory, and TerminateProcess must use the handle returned from OpenProcess.

    This prevents a low privilege application from owning the process space of the high privilege application that it launched. To obtain access to the space of the spawned process, the application must call the OpenProcess function to obtain a full handle to the process. OpenProcess checks the privilege level of the caller before returning a handle to the process. This allows a low privilege application to spawn a high privilege application without then compromising the security of the high privilege application. For example, a shell can launch an administrative or a digital rights management (DRM) application without automatically giving it control over that application.

Return Value

Nonzero indicates success. Zero indicates failure. To get extended error information, call GetLastError.

Remarks

The DebugActiveProcess function and the CreateProcess function enable a debugger thread to create a process and attach to the process or attach to an existing process and debug it. These functions should:

  1. Stop all the threads within the process given by dwProcessId.
  2. Create read and write ends of the message queue in both the debugger and the debuggee processes.
  3. Create a thread to write the current state of the application: creating a process, loading modules, creating debug events, and so on.
  4. Return to the debugger.
  5. When these functions return, the debugger thread needs to call the WaitForDebugEvent function to start processing all the debug events from the target process.

In addition to creating a process, it also creates a thread object.

The size of the initial stack for the thread is described in the image header of the specified program's executable file.

The thread begins execution at the image's entry point.

The process is assigned a 32-bit process identifier. The identifier is valid until the process terminates. It can be used to identify the process, or specified in the OpenProcess function to open a handle to the process.

The initial thread in the process is also assigned a 32-bit thread identifier. The identifier is valid until the thread terminates and can be used to uniquely identify the thread within the system. These identifiers are returned in the PROCESS_INFORMATION structure.

The following list shows the directories indicated by the pszImageName parameter in the order that Windows Embedded Compact searches them:

  1. The windows (\windows) directory.
  2. The root (\) directory of the device.
  3. An OEM-specified directory.

The following list shows the directories indicated by the pszImageName parameter in the order that Windows Embedded Compact searches them:

  1. The windows (\windows) directory.
  2. The root (\) directory of the device.
  3. An OEM-dependent directory.
  4. The OEM-defined shell (\ceshell) directory (Platform Builder users only).

When specifying an application name in the pszImageName string, it does not matter whether the application name includes the filename extension.

Do not call CreateProcess from a DllMain function. This causes the application to stop responding.

The following registry subkey specifies a search path to use with the LoadLibrary function and CreateProcess:

HKEY_LOCAL_MACHINE\Loader
     "SystemPath" = multi_sz:"\\path1\\"
                             "\\path2\\"

The path is only searched if the path of the file being looked for is not explicitly specified.

If the length of the SystemPath value exceeds 260 characters, the path is ignored. A change to the SystemPath key does not take effect until a Windows Embedded Compact powered device is reset.

ExitThread, CreateThread, and a process that is starting (as the result of a call by CreateProcess) are serialized between each other within a process. Only one of these events can happen in an address space at a time. The following list shows the restrictions during the process:

  • During process startup and DLL initialization routines, new threads can be created but they do not begin execution until DLL initialization is completed.
  • In a process, only one thread at a time can be in a DLL initialization or detach routine.

The created process remains in the system until all threads within the process are terminated and all handles to the process and its threads are closed through calls to CloseHandle.

The handles for the process and the main thread must be closed through calls to CloseHandle. If these handles are not needed, close them immediately after the process is created.

The following events occur when the last thread in a process terminates:

  • All objects opened by the process are implicitly closed.
  • The process's termination status, which is returned by GetExitCodeProcess, changes from its initial value of STILL_ACTIVE to the termination status of the last thread to terminate.
  • The thread object of the main thread is set to the signaled state, satisfying threads that were waiting on the object.
  • The process object is set to the signaled state, satisfying threads that were waiting on the object.

Requirements

Header

winbase.h

Library

coredll.lib

See Also

Reference

Process and Thread Functions
CreateThread
DllMain
ExitThread
GetExitCodeProcess
LoadLibrary
OpenProcess
PROCESS_INFORMATION
ReadProcessMemory
ResumeThread
TerminateProcess
WaitForDebugEvent
WriteProcessMemory

Other Resources

CloseHandle