RtCreateProcess

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

Syntax

BOOL RtCreateProcess(
    [in]            LPCTSTR lpApplicationName,
    [in]            LPTSTR lpCommandLine,
    [in, ignored]   LPSECURITY_ATTRIBUTES lpProcessAttributes,
    [in, ignored]   LPSECURITY_ATTRIBUTES lpThreadAttributes,
    [in, ignored]   BOOL bInheritHandles,
    [in]            DWORD dwCreationFlags,
    [in, ignored]   LPVOID lpEnvironment, 
    [in]            LPCTSTR lpCurrentDirectory,         
    [in]            LPSTARTUPINFO lpStartupInfo,
    [in, out]       LPPROCESS_INFORMATION lpProcessInformation
);

Parameters

[in] 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.

[in] 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\MaxRT\wRTOS\bin\Srtm.rtss", _T("srtm.rtss 2"), NULL, NULL, NULL, 0, NULL, NULL, &si, &pi)

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

[in, ignored] lpProcessAttributes

Ignored by wRTOS.

[in, ignored] lpThreadAttributes

Ignored by wRTOS.

[in, ignored] bInheritHandles

Ignored by wRTOS.

[in] 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 wRTOS, it will return ERROR_NOT_SUPPORTED when dwCreationFlags is set to CREATE_SUSPENDED.

[in, ignored] lpEnvironment

Ignored by wRTOS.

[in] lpCurrentDirectory

This parameter does not have the same meaning in wRTOS as in Windows API CreateProcess because wRTOS does not support the concept of a 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.

[in] 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.

[in, out] 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. Call GetLastError to obtain an error code.

Remarks

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

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

The preferred way to shut down an RTSS process is using ExitProcess, which sends notification of approaching termination to all attached RTDLLs. 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 it have terminated and all handles to it 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 RtGetExitCodeProcess returns) 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 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. On Windows 11 machines with AMX enabled, the default stack size is 12 pages.

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, Korean characters, and 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 STARTUPINFOEX structure and 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 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 application no longer needs the process attribute list, 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 but should pass NULL as the ninth parameter.

Requirements

See Also:

• CloseHandle
• ExitProcess
• RtGetExitCodeProcess
• RtOpenProcess
• RtTerminateProcess