gitea/SDL3_fork
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Sync SDL3 wiki -> header

Browse Source
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
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