RtCreateProcess

RtCreateProcess creates and starts a new process. The new process runs the specified Process executable file.

Syntax

BOOL RtCreateProcess(
    LPCTSTR lpApplicationName,
    LPTSTR lpCommandLine,
    LPSECURITY_ATTRIBUTES lpProcessAttributes,     // Ignored by eRTOS
    LPSECURITY_ATTRIBUTES lpThreadAttributes,     // Ignored by eRTOS
    BOOL bInheritHandles,             // Ignored by eRTOS
    DWORD dwCreationFlags,
    LPVOID lpEnvironment,             // Ignored by eRTOS
    LPCTSTR lpCurrentDirectory,         // Ignored by eRTOS
    LPSTARTUPINFO lpStartupInfo,
    LPPROCESS_INFORMATION lpProcessInformation
);

Parameters

lpApplicationName

Pointer to a null-terminated string that specifies the module to execute.

The lpApplicationName parameter can be NULL. In that case, the module name must be the first white space-delimited token in the lpCommandLine string.

The specified module must be a Process application.

lpCommandLine

Pointer to a null-terminated string that specifies the command line to execute. The maximum length of the path is MAX_PATH. The system adds a null character to the command line.

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.

When specifying command line arguments, the name of the binary must precede the argument with a space in between, even when lpApplicationName is specified. For example:

RtCreateProcess(L"C:\\eRTOS\\bin\\Srtm.ertos", _T("srtm.ertos 2"), NULL, NULL, NULL, 0, NULL, NULL, &si, &pi)

If lpApplicationName is NULL, the first white-space - delimited token of the command line specifies the module name.

lpProcessAttributes

Ignored by eRTOS.

lpThreadAttributes

Ignored by eRTOS.

bInheritHandles

Ignored by eRTOS.

dwCreationFlags

A bitwise combination of the Process Creation Flags that control the priority class and the behavior of the launched process. These flags are supported:

• CREATE_SUSPENDED
• EXTENDED_STARTUPINFO_PRESENT

lpEnvironment

Ignored.

lpCurrentDirectory

lpStartupInfo

A pointer to a STARTUPINFO or STARTUPINFOEX structure. To set extended attributes, use a STARTUPINFOEX structure and specify EXTENDED_STARTUPINFO_PRESENT in the dwCreationFlags parameter.

If you are using STARTUPINFOEX, see RtInitializeProcThreadAttributeList for more information.

lpProcessInformation

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

Return Value

If the function succeeds, it returns a non-zero value. If the function fails, it returns zero (0).

To get extended error information, call GetLastError.

Remarks

Flags DEBUG_PROCESS and DEBUG_ONLY_THIS_PROCESS should not be passed to RtCreateProcess, otherwise unexpected behavior will result.

A process can be created and started through Run in a command window. As an alternative way, RtCreateProcess can be used to create and start a new process.

The process handle is returned in the PROCESS_INFORMATION structure. The handle can be used in all functions that perform operations on the process object.

The process is assigned a process identifier. The identifier is valid until the process terminates. It can be used to identify the process or specified in RtOpenProcess to open a handle to the process. The process identifier is returned in the PROCESS_INFORMATION structure.

The preferred way to shut down an process is by using ExitProcess, because this function sends notification of approaching termination to all RTDLLs attached to the process. Other means of shutting down a process do not notify the attached RTDLLs.

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

If this handle is not needed, it is best to close it 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 RtGetExitCodeProcess) changes from its initial value of STILL_ACTIVE to the termination status of the last thread to terminate.
• The process object is set to the signaled state, satisfying any threads that were waiting on the object.

You can set the stack size of the initial thread through linker option /STACK:commit. If you specify 0 (zero), the stack size defaults to 65536 bytes. The stack size is always rounded up to the page size (4096 bytes). For example, if you request 65000 bytes, the allocated amount of memory would be 65536 bytes.

Important: In the Process environment, the stack cannot grow.

Note: RtCreateProcess does not support loading Process and RTDLL files that have pathnames containing Unicode characters with code points greater than 255. These characters include all Japanese, Chinese, Greek, Hebrew, Cyrillic, and Korean characters, as well as characters from many other non-Latin languages. This includes all ASCII and ISO Latin-1 characters, such as 'µ', 'ö', 'é', 'ß', 'ñ', 'ç', etc.

RtCreateProcess ignores all fields in the STARTUPINFO structure and ignores the StartupInfo attribute in the STARTUPINFOEX structure.

To use STARTUPINFOEX process attributes:

1. First, call RtInitializeProcThreadAttributeList to initialize a block of memory so that it is ready to contain a process attribute list. This function should be called once with a NULL pointer as the first parameter to determine how much memory must be allocated to hold the desired number of attributes. Then the memory should be allocated. Then this function should be called a second time with a pointer to the newly allocated memory as the first parameter.
2. Next, call RtUpdateProcThreadAttribute to add one process attribute to the list that was initialized in the previous step. This step can be repeated to add multiple process attributes to the list.
3. Call RtCreateProcess, passing a pointer to the process attribute list as the ninth parameter (lpStartupInfo) and setting the EXTENDED_STARTUPINFO_PRESENT bit in the sixth parameter (dwCreationFlags).
4. When the process attribute list is no longer needed by the application, call RtDeleteProcThreadAttributeList.

Note: If the application doesn’t require process attributes, steps 1, 2, and 4 don’t need to be performed, and the call to RtCreateProcess in step 3 should not set the bit in the sixth parameter and should pass NULL as the ninth parameter.

See Also:

• ExitProcess
• RtGetExitCodeProcess
• RtOpenProcess
• RtTerminateProcess