通过

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.

BOOL CreateProcess( 
LPCWSTR lpszImageName, 
LPCWSTR lpszCmdLine, 
LPSECURITY_ATTRIBUTES lpsaProcess, 
LPSECURITY_ATTRIBUTES lpsaThread, 
BOOL fInheritHandles, 
DWORD fdwCreate, 
LPVOID lpvEnvironment, 
LPWSTR lpszCurDir, 
LPSTARTUPINFOW lpsiStartInfo, 
LPPROCESS_INFORMATION lppiProcInfo);

Parameters

  • lpszImageName
    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.

  • lpszCmdLine
    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 lpszCmdLine parameter can be NULL. In that case, the function uses the string pointed to by lpszImageName as the command line.

    If both 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 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 lpszImageName 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 lpszImageName parameter in the following order:

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

  • lpsaProcess
    Not supported; set to NULL.

  • lpsaThread
    Not supported; set to NULL.

  • fInheritHandles
    Not supported; set to NULL.

  • fdwCreate
    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:

    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. This flag cannot be used with the DETACHED_PROCESS flag.
    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.

    Windows 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.

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

  • lpvEnvironment
    Not supported; set to NULL.

  • lpszCurDir
    Not supported; set to NULL.

  • lpsiStartInfo
    Not supported; set to NULL.

  • lppiProcInfo
    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 lpszImageName string, it doesn't 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\\"

For efficiency, the path is searched before CESH but after the ROM and built in file systems. Note also that the path is only searched if path of the file being looked for is not explicitly specified.

The total length of the SystemPath value cannot exceed 260 characters, or the path will be completely ignored. A change to the SystemPath key does not take effect until a Windows 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. 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.

Thread names are logged. The name of the primary thread for a process is the process name. The names for other threads are the names of the functions they were started with. Windows CE also logs a module handle, which is used to distinguish cases where different modules start threads with the same name. Process and thread names are resolved using the TOC, so thread names will not be logged unless the module is built into the image.

Requirements

Runs on Versions Defined in Include Link to
Windows CE OS 1.0 and later Winbase.h   Coredll.lib, Nk.lib

Note   This API is part of the complete Windows CE OS package as provided by Microsoft. The functionality of a particular platform is determined by the original equipment manufacturer (OEM) and some devices may not support this API.

See Also

CeCreateProcess, CloseHandle, CreateThread, DllMain, ExitThread, GetExitCodeProcess, GetLastError, LoadLibrary, OpenProcess, ResumeThread, TerminateProcess, WaitForDebugEvent, PROCESS_INFORMATION

 Last updated on Tuesday, July 13, 2004

© 1992-2000 Microsoft Corporation. All rights reserved.