Feedback on page SDL3/SDL_CreateProcessWithProperties

[icculus]

These should clarify whether the app needs to destroy the SDL_Environment * afterwards, likewise for the argument pointer. Does this API copy this data, or take ownership of it?

[icculus]

Also should probably say whether it'll accept shell arguments (I assume not), and whether it'll search the $PATH for the command (...maybe?).

[MrOnlineCoder]

@icculus I have found the following info on this:

1. Ownership of SDL_Environment * is not taken, as in both posix and windows it is only used as a source for creating the environment strings:

char** envp = SDL_GetEnvironmentVariables(env); //env is either user passed or current process env

Source: https://github.com/libsdl-org/SDL/blob/main/src/process/windows/SDL_windowsprocess.c#L259

Which is basically a copy, so the suggested edit would be something like "an SDL_Environment pointer. If this property is set, it will be the entire environment for the process, otherwise the current environment is used. If a custom environment is passed, it's data is copied during process creation, and therefore, it is still user's responsibility to free it later with SDL_DestroyEnvironment."

2. In both posix and windows implementations, the program (executable) name is passed to system API in a way that OS performs a search, although a bit wider one on Windows platform.

Windows:

    if (!CreateProcessW(NULL, createprocess_cmdline, NULL, NULL, TRUE, creation_flags, createprocess_env, NULL, &startup_info, &data->process_information)) 

Source: https://github.com/libsdl-org/SDL/blob/3be67ced646f9d884c32ce6858f39fe9dd8d634b/src/process/windows/SDL_windowsprocess.c#L430

In this case, first argument lpApplicationName is NULL and only the second is set (lpCommandLine). According to Microsoft docs (https://learn.microsoft.com/en-us/windows/win32/api/processthreadsapi/nf-processthreadsapi-createprocessw):

If lpApplicationName is NULL, the first white space–delimited token of the command line specifies the module name. If you are using a long file name that contains a space, ..... If the file name does not contain a directory path, the system searches for the executable file in the following sequence:

The directory from which the application loaded.
The current directory for the parent process.
The 32-bit Windows system directory. Use the GetSystemDirectory function to get the path of this directory.
The 16-bit Windows system directory. There is no function that obtains the path of this directory, but it is searched. The name of this directory is System.
The Windows directory. Use the GetWindowsDirectory function to get the path of this directory.
The directories that are listed in the PATH environment variable. Note that this function does not search the per-application path specified by the App Paths registry key. To include this per-application path in the search sequence, use the ShellExecute function.

The same applies to posix implementation, currently SDL uses posix_spawnp:

 if (posix_spawnp(&data->pid, args[0], &fa, &attr, args, envp) != 0) {

From man page (https://linux.die.net/man/3/posix_spawnp):

The file parameter to posix_spawnp() shall be used to construct a pathname that identifies the new process image file. If the file parameter contains a slash character, the file parameter shall be used as the pathname for the new process image file. Otherwise, the path prefix for this file shall be obtained by a search of the directories passed as the environment variable PATH (see the Base Definitions volume of IEEE Std 1003.1-2001, Chapter 8, Environment Variables). If this environment variable is not defined, the results of the search are implementation-defined.

Which means that the search is also performed.

So in result, the suggested edit may either contain simple comment like "If not a full path passed to SDL_CreateProcess(), a search in PATH environment variable will be performed", or can be a more extended one mentioning the difference between two platfroms. Although one thing I am confused about is either the PATH variable is taken from parent process environment, or from the one that is passed to CreateProcess/posix_spawnp system calls, which may actually not contain a PATH at all if user provided custom environment.

3. Could you please elaborate on what do you mean by "accept shell arguments" just to avoid possible confusion?

If you are okay with these edits, I can add them to the wiki.