RtCreateProcess

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

Syntax

BOOL RtCreateProcess(
    LPCTSTR lpApplicationName,
    LPTSTR lpCommandLine,
    LPSECURITY_ATTRIBUTES lpProcessAttributes, 	// Ignored by RTX64
    LPSECURITY_ATTRIBUTES lpThreadAttributes, 	// Ignored by RTX64
    BOOL bInheritHandles, 			// Ignored by RTX64
    DWORD dwCreationFlags,
    LPVOID lpEnvironment, 			// Ignored by RTX64
    LPCTSTR lpCurrentDirectory, 		
    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 an RTSS 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:\\Program Files\\IntervalZero\\RTX64\\bin\\Srtm.rtss", _T("srtm.rtss 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 RTX64.

lpThreadAttributes

Ignored by RTX64.

bInheritHandles

Ignored by RTX64.

dwCreationFlags

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

• CREATE_SUSPENDED
• EXTENDED_STARTUPINFO_PRESENT

NOTE: When RtCreateProcess is called by a Windows application linked to RTX64, it will return ERROR_NOT_SUPPORTED when dwCreationFlags is set to CREATE_SUSPENDED.

lpEnvironment

Ignored by RTX64.

lpCurrentDirectory

This parameter does not have the same meaning in RTX64 as in Windows API CreateProcess, because RTX64 does not support the concept of current directory for real-time processes. Instead, this parameter provides an (optional) additional directory to be searched when RtCreateProcess is given a simple file name (e.g., “program.rtss”) instead of an absolute pathname. See the documentation for parameters lpApplicationName and lpCommandLine for details about this search logic.

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

Nonzero if the function succeeds, Zero if the function fails

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.

Due to compatibility issues, RTSS binaries built with a previous version of the RTX64 SDK may not run on this Runtime. When possible, the Subsystem detects this and displays an error.

You cannot run an RTSS process from a mapped drive.

An RTSS process can be created and started through RTSSrun in a command window. As an alternative way, RtCreateProcess can be used to create and start a new RTSS process through Windows programs.

The RTSS 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 RTSS process is assigned a process identifier. The identifier is valid until the RTSS process terminates. It can be used to identify the RTSS process, or specified in RtOpenProcess to open a handle to the RTSS process. The RTSS process identifier is returned in the PROCESS_INFORMATION structure.

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

The created RTSS process remains in the system until all threads within the RTSS process have terminated and all handles to the RTSS 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 an RTSS process terminates, the following events occur:

• All objects opened by the RTSS 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 RTSS 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 32768 bytes. The stack size is always rounded up to the page size (4096 bytes). For example, if you request 32000 bytes, the allocated amount of memory would be 32768 bytes.

IMPORTANT! In the RTSS environment, the stack cannot grow.

NOTE: RtCreateProcess does not support loading RTSS 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:

CloseHandle

ExitProcess

RtGetExitCodeProcess

RtOpenProcess

RtTerminateProcess