Microsoft Windows CE 3.0  

CreateProcess

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.

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

If both 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 the filename contains a path, .EXE is not appended.

Windows CE versions 2.10 and later search the directories indicated by the lpszImageNameparameter 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 lpszImageNameparameter 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 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.

      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 fdwCreateparameter 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_INFORMATIONstructure 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 CreateProcessfunction is used to run a new program. In addition to creating a process, CreateProcessalso 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 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.

      When specifying an application name in the lpszImageNamestring, it doesn't 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:

      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 SystemPathvalue cannot exceed 260 characters, or the path will be completely ignored. A change to the SystemPathkey 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 CreateProcessfunction 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 Friday, May 26, 2006

          © 2004 Microsoft Corporation. All rights reserved.