Important:
This is retired content. This content is outdated and is no longer being maintained. It is provided as a courtesy for individuals who are still using these technologies. This content may contain URLs that were valid when originally published, but now link to sites or pages that no longer exist.
A version of this page is also available for
4/8/2010

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.

Note:
The remote application interface (RAPI) version of this function is named CeCreateProcess (RAPI).

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 lpszImageNameparameter 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 lpszCmdLineparameter can be NULL. In that case, the function uses the string pointed to by lpszImageNameas the command line.

If lpszImageNameand lpszCmdLineare non-NULL, * lpszImageNamespecifies the module to execute, and * lpszCmdLinespecifies the command line.

C runtime processes can use the argcand argvarguments.

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

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 ResumeThreadfunction 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 WaitForDebugEventfunction.

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 CE 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_INFORMATIONstructure that receives identification information about the new process.

The handle returned by the CreateProcessfunction has PROCESS_ALL_ACCESS access to the process object.

Return Value

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

Remarks

The DebugActiveProcessfunction and the CreateProcessfunction 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 WaitForDebugEventfunction 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 OpenProcessfunction 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_INFORMATIONstructure.

The following list shows the directories indicated by the pszImageNameparameter in the order that Windows Embedded CE 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 pszImageNameparameter in the order that Windows CE 2.10 and later search 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).

The following list shows the directories indicated by the pszImageNameparameter in the order Windows CE 1.0 through 2.01 searches them:

  1. The root of the PC Card, if it exists.

  2. The windows (\windows) directory.

  3. The root (\ ) directory of the device.

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

Do not call CreateProcessfrom a DllMainfunction. This causes the application to stop responding.

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

Copy Code 
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 SystemPathvalue exceeds 260 characters, the path is ignored. A change to the SystemPathkey does not take effect until a Windows Embedded CE-based 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
Windows Embedded CE Windows CE 1.0 and later
Windows Mobile Windows Mobile Version 5.0 and later

See Also