mirrors
/
SDL
mirror of https://github.com/libsdl-org/SDL
1
0
Fork 0
Code Issues Packages Projects Releases Wiki Activity

Sync SDL3 wiki -> header

This commit is contained in:
SDL Wiki Bot 2024-09-14 20:23:16 +00:00
parent 3bc0347761
commit 706aaaf280
2 changed files with 65 additions and 35 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

44
include/SDL3/SDL_process.h
View File

@ -28,9 +28,10 @@
* processes.
*
* You can create a new subprocess with SDL_CreateProcess() and optionally
* read and write to it using SDL_ReadProcess() or SDL_GetProcessInput() and SDL_GetProcessOutput(). If
* more advanced functionality like chaining input between processes is
* necessary, you can use SDL_CreateProcessWithProperties().
* read and write to it using SDL_ReadProcess() or SDL_GetProcessInput() and
* SDL_GetProcessOutput(). If more advanced functionality like chaining input
* between processes is necessary, you can use
* SDL_CreateProcessWithProperties().
*
* You can get the status of a created process with SDL_WaitProcess(), or
* terminate the process with SDL_KillProcess().
@ -66,7 +67,8 @@ typedef struct SDL_Process SDL_Process;
* Setting pipe_stdio to SDL_TRUE is equivalent to setting
* `SDL_PROP_PROCESS_CREATE_STDIN_NUMBER` and
* `SDL_PROP_PROCESS_CREATE_STDOUT_NUMBER` to `SDL_PROCESS_STDIO_APP`, and
* will allow the use of SDL_ReadProcess() or SDL_GetProcessInput() and SDL_GetProcessOutput().
* will allow the use of SDL_ReadProcess() or SDL_GetProcessInput() and
* SDL_GetProcessOutput().
*
* See SDL_CreateProcessWithProperties() for more details.
*
@ -109,9 +111,10 @@ extern SDL_DECLSPEC SDL_Process *SDLCALL SDL_CreateProcess(const char * const *a
* to a new SDL_IOStream that is available to the application. Standard input
* will be available as `SDL_PROP_PROCESS_STDIN_POINTER` and allows
* SDL_GetProcessInput(), standard output will be available as
* `SDL_PROP_PROCESS_STDOUT_POINTER` and allows SDL_ReadProcess() and SDL_GetProcessOutput(), and
* standard error will be available as `SDL_PROP_PROCESS_STDERR_POINTER` in
* the properties for the created process.
* `SDL_PROP_PROCESS_STDOUT_POINTER` and allows SDL_ReadProcess() and
* SDL_GetProcessOutput(), and standard error will be available as
* `SDL_PROP_PROCESS_STDERR_POINTER` in the properties for the created
* process.
*
* If a standard I/O stream is set to SDL_PROCESS_STDIO_REDIRECT, it is
* connected to an existing SDL_IOStream provided by the application. Standard
@ -150,9 +153,9 @@ typedef enum SDL_ProcessIO
* - `SDL_PROP_PROCESS_CREATE_ARGS_POINTER`: an array of strings containing
* the program to run, any arguments, and a NULL pointer, e.g. const char
* *args[] = { "myprogram", "argument", NULL }. This is a required property.
* - `SDL_PROP_PROCESS_CREATE_ENVIRONMENT_POINTER`: an SDL_Environment pointer. If this property is set, it will be the
* entire environment for the process, otherwise the current environment is
* used.
* - `SDL_PROP_PROCESS_CREATE_ENVIRONMENT_POINTER`: an SDL_Environment
* pointer. If this property is set, it will be the entire environment for
* the process, otherwise the current environment is used.
* - `SDL_PROP_PROCESS_CREATE_STDIN_NUMBER`: an SDL_ProcessIO value describing
* where standard input for the process comes from, defaults to
* `SDL_PROCESS_STDIO_NULL`.
@ -175,7 +178,10 @@ typedef enum SDL_ProcessIO
* output of the process should be redirected into the standard output of
* the process. This property has no effect if
* `SDL_PROP_PROCESS_CREATE_STDERR_NUMBER` is set.
* - `SDL_PROP_PROCESS_CREATE_BACKGROUND_BOOLEAN`: true if the process should run in the background. In this case the default input and output is `SDL_PROCESS_STDIO_NULL` and the exitcode of the process is not available, and will always be 0.
* - `SDL_PROP_PROCESS_CREATE_BACKGROUND_BOOLEAN`: true if the process should
* run in the background. In this case the default input and output is
* `SDL_PROCESS_STDIO_NULL` and the exitcode of the process is not
* available, and will always be 0.
*
* On POSIX platforms, wait() and waitpid(-1, ...) should not be called, and
* SIGCHLD should not be ignored or handled because those would prevent SDL
@ -276,9 +282,14 @@ extern SDL_DECLSPEC void * SDLCALL SDL_ReadProcess(SDL_Process *process, size_t
/**
* Get the SDL_IOStream associated with process standard input.
*
* The process must have been created with SDL_CreateProcess() and pipe_stdio set to SDL_TRUE, or with SDL_CreateProcessWithProperties() and `SDL_PROP_PROCESS_CREATE_STDIN_NUMBER` set to `SDL_PROCESS_STDIO_APP`.
* The process must have been created with SDL_CreateProcess() and pipe_stdio
* set to SDL_TRUE, or with SDL_CreateProcessWithProperties() and
* `SDL_PROP_PROCESS_CREATE_STDIN_NUMBER` set to `SDL_PROCESS_STDIO_APP`.
*
* Writing to this stream can return less data than expected if the process hasn't read its input. It may be blocked waiting for its output to be read, so if you may need to call SDL_GetOutputStream() and read the output in parallel with writing input.
* Writing to this stream can return less data than expected if the process
* hasn't read its input. It may be blocked waiting for its output to be read,
* so if you may need to call SDL_GetOutputStream() and read the output in
* parallel with writing input.
*
* \param process The process to get the input stream for.
* \returns the input stream or NULL on failure; call SDL_GetError() for more
@ -297,9 +308,12 @@ extern SDL_DECLSPEC SDL_IOStream *SDLCALL SDL_GetProcessInput(SDL_Process *proce
/**
* Get the SDL_IOStream associated with process standard output.
*
* The process must have been created with SDL_CreateProcess() and pipe_stdio set to SDL_TRUE, or with SDL_CreateProcessWithProperties() and `SDL_PROP_PROCESS_CREATE_STDOUT_NUMBER` set to `SDL_PROCESS_STDIO_APP`.
* The process must have been created with SDL_CreateProcess() and pipe_stdio
* set to SDL_TRUE, or with SDL_CreateProcessWithProperties() and
* `SDL_PROP_PROCESS_CREATE_STDOUT_NUMBER` set to `SDL_PROCESS_STDIO_APP`.
*
* Reading from this stream can return 0 with SDL_GetIOStatus() returning SDL_IO_STATUS_NOT_READY if no output is available yet.
* Reading from this stream can return 0 with SDL_GetIOStatus() returning
* SDL_IO_STATUS_NOT_READY if no output is available yet.
*
* \param process The process to get the output stream for.
* \returns the output stream or NULL on failure; call SDL_GetError() for more

56
include/SDL3/SDL_stdinc.h
View File

@ -997,10 +997,12 @@ typedef struct SDL_Environment SDL_Environment;
/**
* Get the process environment.
*
* This is initialized at application start and is not affected by setenv() and unsetenv() calls after that point. Use SDL_SetEnvironmentVariable() and SDL_UnsetEnvironmentVariable() if you want to modify this environment.
* This is initialized at application start and is not affected by setenv()
* and unsetenv() calls after that point. Use SDL_SetEnvironmentVariable() and
* SDL_UnsetEnvironmentVariable() if you want to modify this environment.
*
* \returns a pointer to the environment for the process or NULL on failure; call SDL_GetError()
* for more information.
* \returns a pointer to the environment for the process or NULL on failure;
* call SDL_GetError() for more information.
*
* \threadsafety It is safe to call this function from any thread.
*
@ -1017,7 +1019,9 @@ extern SDL_DECLSPEC SDL_Environment * SDLCALL SDL_GetEnvironment(void);
/**
* Cleanup the process environment.
*
* This is called during SDL_Quit() to free the process environment. If SDL_GetEnvironment() is called afterwards, it will automatically create a new environment copied from the C runtime environment.
* This is called during SDL_Quit() to free the process environment. If
* SDL_GetEnvironment() is called afterwards, it will automatically create a
* new environment copied from the C runtime environment.
*
* \threadsafety This function is not thread-safe.
*
@ -1030,11 +1034,14 @@ extern SDL_DECLSPEC void SDLCALL SDL_CleanupEnvironment(void);
/**
* Create a set of environment variables
*
* \param populated SDL_TRUE to initialize it from the C runtime environment, SDL_FALSE to create an empty environment.
* \returns a pointer to the new environment or NULL on failure; call SDL_GetError()
* for more information.
* \param populated SDL_TRUE to initialize it from the C runtime environment,
* SDL_FALSE to create an empty environment.
* \returns a pointer to the new environment or NULL on failure; call
* SDL_GetError() for more information.
*
* \threadsafety If `populated` is SDL_FALSE, it is safe to call this function from any thread, otherwise it is safe if no other threads are calling setenv() or unsetenv()
* \threadsafety If `populated` is SDL_FALSE, it is safe to call this function
* from any thread, otherwise it is safe if no other threads are
* calling setenv() or unsetenv()
*
* \since This function is available since SDL 3.0.0.
*
@ -1051,7 +1058,8 @@ extern SDL_DECLSPEC SDL_Environment * SDLCALL SDL_CreateEnvironment(SDL_bool pop
*
* \param env the environment to query.
* \param name the name of the variable to get.
* \returns a pointer to the value of the variable or NULL if it can't be found.
* \returns a pointer to the value of the variable or NULL if it can't be
* found.
*
* \threadsafety It is safe to call this function from any thread.
*
@ -1069,10 +1077,10 @@ extern SDL_DECLSPEC const char * SDLCALL SDL_GetEnvironmentVariable(SDL_Environm
* Get all variables in the environment.
*
* \param env the environment to query.
* \returns a NULL terminated array of pointers to environment variables in the form "variable=value" or NULL on
* failure; call SDL_GetError() for more information. This is a
* single allocation that should be freed with SDL_free() when it is
* no longer needed.
* \returns a NULL terminated array of pointers to environment variables in
* the form "variable=value" or NULL on failure; call SDL_GetError()
* for more information. This is a single allocation that should be
* freed with SDL_free() when it is no longer needed.
*
* \threadsafety It is safe to call this function from any thread.
*
@ -1092,7 +1100,9 @@ extern SDL_DECLSPEC char ** SDLCALL SDL_GetEnvironmentVariables(SDL_Environment
* \param env the environment to modify.
* \param name the name of the variable to set.
* \param value the value of the variable to set.
* \param overwrite SDL_TRUE to overwrite the variable if it exists, SDL_FALSE to return success without setting the variable if it already exists.
* \param overwrite SDL_TRUE to overwrite the variable if it exists, SDL_FALSE
* to return success without setting the variable if it
* already exists.
* \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError()
* for more information.
*
@ -1134,7 +1144,8 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_UnsetEnvironmentVariable(SDL_Environmen
*
* \param env the environment to destroy.
*
* \threadsafety It is safe to call this function from any thread, as long as the environment is no longer in use.
* \threadsafety It is safe to call this function from any thread, as long as
* the environment is no longer in use.
*
* \since This function is available since SDL 3.0.0.
*
@ -1146,9 +1157,11 @@ extern SDL_DECLSPEC void SDLCALL SDL_DestroyEnvironment(SDL_Environment *env);
* Get the value of a variable in the environment.
*
* \param name the name of the variable to get.
* \returns a pointer to the value of the variable or NULL if it can't be found.
* \returns a pointer to the value of the variable or NULL if it can't be
* found.
*
* \threadsafety This function is not thread safe, consider using SDL_GetEnvironmentVariable() instead.
* \threadsafety This function is not thread safe, consider using
* SDL_GetEnvironmentVariable() instead.
*
* \since This function is available since SDL 3.0.0.
*
@ -1161,10 +1174,12 @@ extern SDL_DECLSPEC const char * SDLCALL SDL_getenv_unsafe(const char *name);
*
* \param name the name of the variable to set.
* \param value the value of the variable to set.
* \param overwrite 1 to overwrite the variable if it exists, 0 to return success without setting the variable if it already exists.
* \param overwrite 1 to overwrite the variable if it exists, 0 to return
* success without setting the variable if it already exists.
* \returns 0 on success, -1 on error.
*
* \threadsafety This function is not thread safe, consider using SDL_SetEnvironmentVariable() instead.
* \threadsafety This function is not thread safe, consider using
* SDL_SetEnvironmentVariable() instead.
*
* \since This function is available since SDL 3.0.0.
*
@ -1178,7 +1193,8 @@ extern SDL_DECLSPEC int SDLCALL SDL_setenv_unsafe(const char *name, const char *
* \param name the name of the variable to unset.
* \returns 0 on success, -1 on error.
*
* \threadsafety This function is not thread safe, consider using SDL_UnsetEnvironmentVariable() instead..
* \threadsafety This function is not thread safe, consider using
* SDL_UnsetEnvironmentVariable() instead..
*
* \since This function is available since SDL 3.0.0.
*