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

Revert "Sync SDL3 wiki -> header" 

This reverts commit 35427ff9ec.
This commit is contained in:
Ryan C. Gordon 2024-09-14 16:22:16 -04:00
parent c2e4b14a82
commit 3bc0347761
No known key found for this signature in database
GPG Key ID: FA148B892AB48044
2 changed files with 36 additions and 62 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

44
include/SDL3/SDL_process.h
View File

@ -28,7 +28,7 @@
* processes.
*
* You can create a new subprocess with SDL_CreateProcess() and optionally
* read and write to it using SDL_ReadProcess() and SDL_WriteProcess(). If
* 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().
*
@ -66,7 +66,7 @@ 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() and SDL_WriteProcess().
* will allow the use of SDL_ReadProcess() or SDL_GetProcessInput() and SDL_GetProcessOutput().
*
* See SDL_CreateProcessWithProperties() for more details.
*
@ -85,7 +85,8 @@ typedef struct SDL_Process SDL_Process;
* \sa SDL_CreateProcessWithProperties
* \sa SDL_GetProcessProperties
* \sa SDL_ReadProcess
* \sa SDL_WriteProcess
* \sa SDL_GetProcessInput
* \sa SDL_GetProcessOutput
* \sa SDL_KillProcess
* \sa SDL_WaitProcess
* \sa SDL_DestroyProcess
@ -107,8 +108,8 @@ extern SDL_DECLSPEC SDL_Process *SDLCALL SDL_CreateProcess(const char * const *a
* If a standard I/O stream is set to SDL_PROCESS_STDIO_APP, it is connected
* 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_WriteProcess(), standard output will be available as
* `SDL_PROP_PROCESS_STDOUT_POINTER` and allows SDL_ReadProcess(), and
* 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.
*
@ -130,7 +131,8 @@ extern SDL_DECLSPEC SDL_Process *SDLCALL SDL_CreateProcess(const char * const *a
* \sa SDL_CreateProcessWithProperties
* \sa SDL_GetProcessProperties
* \sa SDL_ReadProcess
* \sa SDL_WriteProcess
* \sa SDL_GetProcessInput
* \sa SDL_GetProcessOutput
*/
typedef enum SDL_ProcessIO
{
@ -148,9 +150,7 @@ 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 array of strings
* containing variable=value, and a NULL pointer, e.g. const char *env[] = {
* "PATH=/bin:/usr/bin", NULL }. If this property is set, it will be the
* - `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
@ -175,6 +175,7 @@ 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.
*
* On POSIX platforms, wait() and waitpid(-1, ...) should not be called, and
* SIGCHLD should not be ignored or handled because those would prevent SDL
@ -192,7 +193,8 @@ typedef enum SDL_ProcessIO
* \sa SDL_CreateProcess
* \sa SDL_GetProcessProperties
* \sa SDL_ReadProcess
* \sa SDL_WriteProcess
* \sa SDL_GetProcessInput
* \sa SDL_GetProcessOutput
* \sa SDL_KillProcess
* \sa SDL_WaitProcess
* \sa SDL_DestroyProcess
@ -247,10 +249,6 @@ extern SDL_DECLSPEC SDL_PropertiesID SDL_GetProcessProperties(SDL_Process *proce
* read the output. This function blocks until the process is complete,
* capturing all output, and providing the process exit code.
*
* This is just a convenience function. If you need more control over the
* process, you can get the output stream from the process properties and read
* it directly.
*
* The data is allocated with a zero byte at the end (null terminated) for
* convenience. This extra byte is not included in the value reported via
* `datasize`.
@ -271,8 +269,6 @@ extern SDL_DECLSPEC SDL_PropertiesID SDL_GetProcessProperties(SDL_Process *proce
*
* \sa SDL_CreateProcess
* \sa SDL_CreateProcessWithProperties
* \sa SDL_GetProcessProperties
* \sa SDL_WriteProcess
* \sa SDL_DestroyProcess
*/
extern SDL_DECLSPEC void * SDLCALL SDL_ReadProcess(SDL_Process *process, size_t *datasize, int *exitcode);
@ -280,14 +276,9 @@ 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
@ -306,12 +297,9 @@ 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

54
include/SDL3/SDL_stdinc.h
View File

@ -997,12 +997,10 @@ 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.
*
@ -1019,9 +1017,7 @@ 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.
*
@ -1034,12 +1030,11 @@ extern SDL_DECLSPEC void SDLCALL SDL_CleanupEnvironment(void);
/**
* Create a set of environment variables
*
* \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 `empty` is SDL_TRUE, 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.
*
@ -1056,8 +1051,7 @@ 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.
*
@ -1075,10 +1069,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.
*
@ -1098,9 +1092,7 @@ 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.
*
@ -1142,8 +1134,7 @@ 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.
*
@ -1155,11 +1146,9 @@ 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.
*
@ -1172,12 +1161,10 @@ 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.
*
@ -1191,8 +1178,7 @@ 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.
*