---
name: "SDL_CreateThreadWithProperties"
section: "3"
platform: "linux"
package: "libsdl3-doc"
version: "3.2.10+ds-1"
release: "Debian 13 (Trixie)"
platforms: ["linux"]
url: "https://new.carta.tech/SDL_CreateThreadWithProperties"
---

# SDL\_CreateThreadWithProperties(3)

Create a new thread with with the specified properties.

## NAME

SDL\_CreateThreadWithProperties - Create a new thread with with the specified properties.

## HEADER FILE

Defined in SDL3/SDL\_thread.h

## SYNOPSIS

```
#include "SDL3/SDL.h"
```

**SDL\_Thread \* SDL\_CreateThreadWithProperties(SDL\_PropertiesID props);**

## DESCRIPTION

These are the supported properties:

•  **SDL\_PROP\_THREAD\_CREATE\_ENTRY\_FUNCTION\_POINTER** :\
   an  **SDL\_ThreadFunction**\
  value that will be called at\
   the start of the new thread's life. Required.

•  **SDL\_PROP\_THREAD\_CREATE\_NAME\_STRING** :\
   the name of the new thread, which might be available to debuggers.\
   Optional, defaults to NULL.

•  **SDL\_PROP\_THREAD\_CREATE\_USERDATA\_POINTER** :\
   an arbitrary app-defined pointer, which is passed to the entry function\
   on the new thread, as its only parameter. Optional, defaults to NULL.

•  **SDL\_PROP\_THREAD\_CREATE\_STACKSIZE\_NUMBER** :\
   the size, in bytes, of the new thread's stack. Optional, defaults to 0\
   (system-defined default).

SDL makes an attempt to report

**SDL\_PROP\_THREAD\_CREATE\_NAME\_STRING** to the system, so that debuggers can display it. Not all platforms support this.

Thread naming is a little complicated: Most systems have very small limits for the string length (Haiku has 32 bytes, Linux currently has 16, Visual C++ 6.0 has \_nine\_!), and possibly other arbitrary rules. You'll have to see what happens with your system's debugger. The name should be UTF-8 (but using the naming limits of C identifiers is a better bet). There are no requirements for thread naming conventions, so long as the string is null-terminated UTF-8, but these guidelines are helpful in choosing a name:

https://stackoverflow.com/questions/149932/naming-conventions-for-threads

If a system imposes requirements, SDL will try to munge the string for it (truncate, etc), but the original string contents will be available from

**SDL\_GetThreadName** ().

The size (in bytes) of the new stack can be specified with

**SDL\_PROP\_THREAD\_CREATE\_STACKSIZE\_NUMBER** . Zero means "use the system default" which might be wildly different between platforms. x86 Linux generally defaults to eight megabytes, an embedded device might be a few kilobytes instead. You generally need to specify a stack that is a multiple of the system's page size (in many cases, this is 4 kilobytes, but check your system documentation).

Note that this "function" is actually a macro that calls an internal function with two extra parameters not listed here; they are hidden through preprocessor macros and are needed to support various C runtimes at the point of the function call. Language bindings that aren't using the C headers will need to deal with this.

The actual symbol in SDL is

**SDL\_CreateThreadWithPropertiesRuntime** , so there is no symbol clash, but trying to load an SDL shared library and look for " **SDL\_CreateThreadWithProperties** " will fail.

Usually, apps should just call this function the same way on every platform and let the macros hide the details.

## FUNCTION PARAMETERS

- *props*

  the properties to use.

## RETURN VALUE

( **SDL\_Thread**\
  \*) Returns an opaque pointer to the new thread object on success, NULL if the new thread could not be created; call

**SDL\_GetError** () for more information.

## AVAILABILITY

This function is available since SDL 3.2.0.

## SEE ALSO

**•**(3), [**SDL\_CreateThread**(3)](/SDL_CreateThread/3.md), **•**(3), [**SDL\_WaitThread**(3)](/SDL_WaitThread/3.md)