Document that you can pass NULL to SDL_PeepEvents()

Fixes https://github.com/libsdl-org/sdlwiki/issues/547

include/SDL3/SDL_events.h

@@ -929,15 +929,15 @@ typedef enum SDL_EventAction
  *
  * This function is thread-safe.
  *
- * \param events destination buffer for the retrieved events
+ * \param events destination buffer for the retrieved events, may be NULL to leave the events in the queue and return the number of events that would have been stored.
  * \param numevents if action is SDL_ADDEVENT, the number of events to add
  *                  back to the event queue; if action is SDL_PEEKEVENT or
- *                  SDL_GETEVENT, the maximum number of events to retrieve
- * \param action action to take; see [[#action|Remarks]] for details
+ *                  SDL_GETEVENT, the maximum number of events to retrieve.
+ * \param action action to take; see [[#action|Remarks]] for details.
  * \param minType minimum value of the event type to be considered;
- *                SDL_EVENT_FIRST is a safe choice
+ *                SDL_EVENT_FIRST is a safe choice.
  * \param maxType maximum value of the event type to be considered;
- *                SDL_EVENT_LAST is a safe choice
+ *                SDL_EVENT_LAST is a safe choice.
  * \returns the number of events actually stored or a negative error code on
  *          failure; call SDL_GetError() for more information.
  *

src/events/SDL_events.c

@@ -878,6 +878,10 @@ static int SDL_PeepEventsInternal(SDL_Event *events, int numevents, SDL_EventAct
             return -1;
         }
         if (action == SDL_ADDEVENT) {
+            if (!events) {
+                SDL_UnlockMutex(SDL_EventQ.lock);
+                return SDL_InvalidParamError("events");
+            }
             for (i = 0; i < numevents; ++i) {
                 used += SDL_AddEvent(&events[i]);
             }