From f81472d767b50fa90ee16ce348d0825127845efd Mon Sep 17 00:00:00 2001
From: Sam Lantinga <slouken@libsdl.org>
Date: Wed, 18 Dec 2024 16:18:44 -0800
Subject: [PATCH] Document that you should read from processes before waiting
 for them to exit.

Fixes https://github.com/libsdl-org/SDL/issues/11645
---
 include/SDL3/SDL_process.h | 2 ++
 1 file changed, 2 insertions(+)

diff --git a/include/SDL3/SDL_process.h b/include/SDL3/SDL_process.h
index 55be8d4219..ae854c6f2d 100644
--- a/include/SDL3/SDL_process.h
+++ b/include/SDL3/SDL_process.h
@@ -371,6 +371,8 @@ extern SDL_DECLSPEC bool SDLCALL SDL_KillProcess(SDL_Process *process, bool forc
  * normally, a negative signal if it terminated due to a signal, or -255
  * otherwise. It will not be changed if the process is still running.
  *
+ * If you create a process with standard output piped to the application (`pipe_stdio` being true) then you should read all of the process output before calling SDL_WaitProcess(). If you don't do this the process might be blocked indefinitely waiting for output to be read and SDL_WaitProcess() will never return true;
+ *
  * \param process The process to wait for.
  * \param block If true, block until the process finishes; otherwise, report
  *              on the process' status.