CreateProcess

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

A remote application interface (RAPI) version of this function exists, and it is named CeCreateProcess.

At a Glance

Syntax

BOOL CreateProcess( LPCTSTR lpApplicationName,
LPTSTR lpCommandLine,
LPSECURITY_ATTRIBUTES lpProcessAttributes, LPSECURITY_ATTRIBUTES lpThreadAttributes,
BOOL bInheritHandles, DWORD dwCreationFlags, LPVOID lpEnvironment,
LPCTSTR lpCurrentDirectory, LPSTARTUPINFO lpStartupInfo,
LPPROCESS_INFORMATION lpProcessInformation );

Parameters

lpApplicationName

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 name. In the case of a partial name, the function uses the current drive and current directory to complete the specification.

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

lpCommandLine

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 actually used.

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

If both lpApplicationName and lpCommandLine are non-NULL, *lpApplicationName specifies the module to execute, and *lpCommandLine specifies the command line. C runtime processes can use the argc and argv arguments.

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

Windows CE versions 2.10 and later search the directories indicated by the lpApplicationName parameter in the following order:

• The windows (\windows) directory
  
  
• The root (\) directory of the device
  
  
• An OEM-dependent directory
  
  
• The OEM-defined shell (\ceshell) directory — Platform Builder users only

Windows CE versions 1.0 through 2.01 search the directories indicated by the lpApplicationName parameter in the following order:

• The root of the PC Card, if it exists
  
  
• The windows (\windows) directory
  
  
• The root (\ ) directory of the device

lpProcessAttributes

Not supported; set to NULL.

lpThreadAttributes

Not supported; set to NULL.

bInheritHandles

Not supported; set to NULL.

dwCreationFlags

Specifies additional flags that control the priority class and the creation of the process. The following creation flags can be specified in any combination, except as noted:

Windows CE does not support the concept of a priority class. The priority of a thread is the only parameter that determines a threads scheduling priority.

For Windows CE version 1.0 and 1.01, the dwCreationFlags parameter only supports the following values: CREATE_SUSPENDED and zero.

lpEnvironment

Not supported; set to NULL.

lpCurrentDirectory

Not supported; set to NULL.

lpStartupInfo

Not supported; set to NULL.

lpProcessInformation

Pointer to a PROCESS_INFORMATION structure that receives identification information about the new process.

Return Values

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

Remarks

The CreateProcess function is used to run a new program. In addition to creating a process, CreateProcess also creates a thread object. The thread is created with an initial stack whose size is described in the image header of the specified program’s executable file. The thread begins execution at the image’s entry point.

The new process and the new thread handles are created with full access rights. For either handle, the handle can be used in any function that requires an object handle to that type.

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.

When specifying an application name in the lpApplicationName string, it doesn’t matter whether the application name includes the filename extension.

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. This means the following restrictions hold:

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

The created process remains in the system until all threads within the process have terminated and all handles to the process and any of its threads have been closed through calls to CloseHandle. The handles for both the process and the main thread must be closed through calls to CloseHandle. If these handles are not needed, it is best to close them immediately after the process is created.

When the last thread in a process terminates, the following events occur:

• 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 any threads that were waiting on the object.
  
  
• The process object is set to the signaled state, satisfying any threads that were waiting on the object.

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

See Also

CloseHandle, CreateThread, ExitThread, PROCESS_INFORMATION, ResumeThread, TerminateProcess