sdl3-bindgen-sys
Safe HaskellNone
LanguageGHC2021

SDL3.Sys.Stdinc

Description

SDL's C-library replacements: memory, strings, math, and conversions; this module aliases the allocator and SDL's own API.

FFI conventions

Unsuffixed aliases are unsafe foreign imports; aliases suffixed Safe are safe. Functions whose callbacks fire during the call export only the Safe alias (the genuine unsafe import stays reachable under SDL3.Sys.Bindgen.Stdinc.Unsafe); functions curated unsafe-only export only the unsuffixed one. Each alias's documentation records its flavor and rationale.

This module aliases only the functions of SDL_stdinc.h that the registry allowlists. The header's other functions are raw-only: SDL3.Sys.Bindgen.Stdinc.Unsafe and SDL3.Sys.Bindgen.Stdinc.Safe export them.

The C shims are functions this package defines in C over what the FFI cannot call directly (variadic functions, function-like macros), each named after what it wraps; the same flavor rules apply. Their raw imports live under SDL3.Sys.Bindgen.StdincShims.

Full conventions: SDL3.Sys.

Allowlist

The aliases are SDL's own API in this header (environments, the memory-function hooks and allocation count, UTF-8 stepping) and the allocator family, since memory SDL frees, or hands you to free, must come from SDL's allocator: malloc, free, strdup, and their kin. The rest of the header serves C programs without a portable C library: strings, character classes, math, sorting, random numbers, checksums, iconv, memcpy. Haskell has its own, so they stay raw-only.

Synopsis

Documentation

module SDL3.Sys.Bindgen.Stdinc

Typed constants

pattern SDL_MAX_TIME :: SDL_Time Source #

Typed constant for macro SDL_MAX_TIME.

pattern SDL_MIN_TIME :: SDL_Time Source #

Typed constant for macro SDL_MIN_TIME.

pattern SDL_MAX_SINT16 :: Sint16 Source #

Typed constant for macro SDL_MAX_SINT16.

pattern SDL_MIN_SINT16 :: Sint16 Source #

Typed constant for macro SDL_MIN_SINT16.

pattern SDL_MAX_SINT32 :: Sint32 Source #

Typed constant for macro SDL_MAX_SINT32.

pattern SDL_MIN_SINT32 :: Sint32 Source #

Typed constant for macro SDL_MIN_SINT32.

pattern SDL_MAX_SINT64 :: Sint64 Source #

Typed constant for macro SDL_MAX_SINT64.

pattern SDL_MIN_SINT64 :: Sint64 Source #

Typed constant for macro SDL_MIN_SINT64.

pattern SDL_MAX_SINT8 :: Sint8 Source #

Typed constant for macro SDL_MAX_SINT8.

pattern SDL_MIN_SINT8 :: Sint8 Source #

Typed constant for macro SDL_MIN_SINT8.

pattern SDL_MAX_UINT16 :: Uint16 Source #

Typed constant for macro SDL_MAX_UINT16.

pattern SDL_MIN_UINT16 :: Uint16 Source #

Typed constant for macro SDL_MIN_UINT16.

pattern SDL_MAX_UINT32 :: Uint32 Source #

Typed constant for macro SDL_MAX_UINT32.

pattern SDL_MIN_UINT32 :: Uint32 Source #

Typed constant for macro SDL_MIN_UINT32.

pattern SDL_MAX_UINT64 :: Uint64 Source #

Typed constant for macro SDL_MAX_UINT64.

pattern SDL_MIN_UINT64 :: Uint64 Source #

Typed constant for macro SDL_MIN_UINT64.

pattern SDL_MAX_UINT8 :: Uint8 Source #

Typed constant for macro SDL_MAX_UINT8.

pattern SDL_MIN_UINT8 :: Uint8 Source #

Typed constant for macro SDL_MIN_UINT8.

pattern SDL_SIZE_MAX :: Word64 Source #

Typed constant for macro SDL_SIZE_MAX (C type size_t).

pattern SDL_ICONV_ERROR :: Word64 Source #

Typed constant for macro SDL_ICONV_ERROR (C type size_t).

pattern SDL_ICONV_E2BIG :: Word64 Source #

Typed constant for macro SDL_ICONV_E2BIG (C type size_t).

pattern SDL_ICONV_EILSEQ :: Word64 Source #

Typed constant for macro SDL_ICONV_EILSEQ (C type size_t).

pattern SDL_ICONV_EINVAL :: Word64 Source #

Typed constant for macro SDL_ICONV_EINVAL (C type size_t).

Function aliases

malloc Source #

Arguments

:: Word64
size
the size to allocate.
-> IO (Ptr Void) 

Allocate uninitialized memory.

The allocated memory returned by this function must be freed with free.

If size is 0, it will be set to 1.

If the allocation is successful, the returned pointer is guaranteed to be aligned to either the fundamental alignment (alignof(max_align_t) in C11 and later) or 2 * sizeof(void *), whichever is smaller. Use alignedAlloc if you need to allocate memory aligned to an alignment greater than this guarantee.

Returns
a pointer to the allocated memory, or NULL if allocation failed.
Thread safety
It is safe to call this function from any thread.
See also
free, calloc, realloc, alignedAlloc

sdl3-bindgen-sys notes

Expand
FFI safety
Unsafe foreign import of SDL_malloc. The safe flavor is mallocSafe .
Scalars
The binding generation has mapped C scalars to native Haskell scalars for this function. Pointers and structs are untouched by this best-effort mapping. Higher-level bindings are expected to map structs and pointers as appropriate.
C declaration
SDL_malloc, defined at SDL3/SDL_stdinc.h 1342:47

Since: 3.2.0

mallocSafe Source #

Arguments

:: Word64
size
the size to allocate.
-> IO (Ptr Void) 

Allocate uninitialized memory.

The allocated memory returned by this function must be freed with free.

If size is 0, it will be set to 1.

If the allocation is successful, the returned pointer is guaranteed to be aligned to either the fundamental alignment (alignof(max_align_t) in C11 and later) or 2 * sizeof(void *), whichever is smaller. Use alignedAlloc if you need to allocate memory aligned to an alignment greater than this guarantee.

Returns
a pointer to the allocated memory, or NULL if allocation failed.
Thread safety
It is safe to call this function from any thread.
See also
free, calloc, realloc, alignedAlloc

sdl3-bindgen-sys notes

Expand
FFI safety
Safe foreign import of SDL_malloc. The unsafe flavor is malloc .
Scalars
The binding generation has mapped C scalars to native Haskell scalars for this function. Pointers and structs are untouched by this best-effort mapping. Higher-level bindings are expected to map structs and pointers as appropriate.
C declaration
SDL_malloc, defined at SDL3/SDL_stdinc.h 1342:47

Since: 3.2.0

calloc Source #

Arguments

:: Word64
C declaration
nmemb
-> Word64
C declaration
size
-> IO (Ptr Void) 

sdl3-bindgen-sys notes

Expand
FFI safety
Unsafe foreign import of SDL_calloc. The safe flavor is callocSafe .
Scalars
The binding generation has mapped C scalars to native Haskell scalars for this function. Pointers and structs are untouched by this best-effort mapping. Higher-level bindings are expected to map structs and pointers as appropriate.
C declaration
SDL_calloc, defined at SDL3/SDL_stdinc.h 1367:69

callocSafe Source #

Arguments

:: Word64
C declaration
nmemb
-> Word64
C declaration
size
-> IO (Ptr Void) 

sdl3-bindgen-sys notes

Expand
FFI safety
Safe foreign import of SDL_calloc. The unsafe flavor is calloc .
Scalars
The binding generation has mapped C scalars to native Haskell scalars for this function. Pointers and structs are untouched by this best-effort mapping. Higher-level bindings are expected to map structs and pointers as appropriate.
C declaration
SDL_calloc, defined at SDL3/SDL_stdinc.h 1367:69

realloc Source #

Arguments

:: Ptr Void
C declaration
mem
-> Word64
C declaration
size
-> IO (Ptr Void) 

sdl3-bindgen-sys notes

Expand
FFI safety
Unsafe foreign import of SDL_realloc. The safe flavor is reallocSafe .
Scalars
The binding generation has mapped C scalars to native Haskell scalars for this function. Pointers and structs are untouched by this best-effort mapping. Higher-level bindings are expected to map structs and pointers as appropriate.
C declaration
SDL_realloc, defined at SDL3/SDL_stdinc.h 1407:54

reallocSafe Source #

Arguments

:: Ptr Void
C declaration
mem
-> Word64
C declaration
size
-> IO (Ptr Void) 

sdl3-bindgen-sys notes

Expand
FFI safety
Safe foreign import of SDL_realloc. The unsafe flavor is realloc .
Scalars
The binding generation has mapped C scalars to native Haskell scalars for this function. Pointers and structs are untouched by this best-effort mapping. Higher-level bindings are expected to map structs and pointers as appropriate.
C declaration
SDL_realloc, defined at SDL3/SDL_stdinc.h 1407:54

free Source #

Arguments

:: Ptr Void
mem
a pointer to allocated memory, or NULL.
-> IO () 

Free allocated memory.

The pointer is no longer valid after this call and cannot be dereferenced anymore.

If mem is NULL, this function does nothing.

Thread safety
It is safe to call this function from any thread.
See also
malloc, calloc, realloc

sdl3-bindgen-sys notes

Expand
FFI safety
Unsafe foreign import of SDL_free. The safe flavor is freeSafe .
C declaration
SDL_free, defined at SDL3/SDL_stdinc.h 1427:34

Since: 3.2.0

freeSafe Source #

Arguments

:: Ptr Void
mem
a pointer to allocated memory, or NULL.
-> IO () 

Free allocated memory.

The pointer is no longer valid after this call and cannot be dereferenced anymore.

If mem is NULL, this function does nothing.

Thread safety
It is safe to call this function from any thread.
See also
malloc, calloc, realloc

sdl3-bindgen-sys notes

Expand
FFI safety
Safe foreign import of SDL_free. The unsafe flavor is free .
C declaration
SDL_free, defined at SDL3/SDL_stdinc.h 1427:34

Since: 3.2.0

getOriginalMemoryFunctions Source #

Arguments

:: Ptr SDL_malloc_func
malloc_func
filled with malloc function.
-> Ptr SDL_calloc_func
calloc_func
filled with calloc function.
-> Ptr SDL_realloc_func
realloc_func
filled with realloc function.
-> Ptr SDL_free_func
free_func
filled with free function.
-> IO () 

Get the original set of SDL memory functions.

This is what malloc and friends will use by default, if there has been no call to setMemoryFunctions. This is not necessarily using the C runtime's malloc functions behind the scenes! Different platforms and build configurations might do any number of unexpected things.

Thread safety
It is safe to call this function from any thread.

sdl3-bindgen-sys notes

Expand
FFI safety
Unsafe foreign import of SDL_GetOriginalMemoryFunctions. The safe flavor is getOriginalMemoryFunctionsSafe .
C declaration
SDL_GetOriginalMemoryFunctions, defined at SDL3/SDL_stdinc.h 1525:34

Since: 3.2.0

getOriginalMemoryFunctionsSafe Source #

Arguments

:: Ptr SDL_malloc_func
malloc_func
filled with malloc function.
-> Ptr SDL_calloc_func
calloc_func
filled with calloc function.
-> Ptr SDL_realloc_func
realloc_func
filled with realloc function.
-> Ptr SDL_free_func
free_func
filled with free function.
-> IO () 

Get the original set of SDL memory functions.

This is what malloc and friends will use by default, if there has been no call to setMemoryFunctions. This is not necessarily using the C runtime's malloc functions behind the scenes! Different platforms and build configurations might do any number of unexpected things.

Thread safety
It is safe to call this function from any thread.

sdl3-bindgen-sys notes

Expand
FFI safety
Safe foreign import of SDL_GetOriginalMemoryFunctions. The unsafe flavor is getOriginalMemoryFunctions .
C declaration
SDL_GetOriginalMemoryFunctions, defined at SDL3/SDL_stdinc.h 1525:34

Since: 3.2.0

getMemoryFunctions Source #

Arguments

:: Ptr SDL_malloc_func
malloc_func
filled with malloc function.
-> Ptr SDL_calloc_func
calloc_func
filled with calloc function.
-> Ptr SDL_realloc_func
realloc_func
filled with realloc function.
-> Ptr SDL_free_func
free_func
filled with free function.
-> IO () 

Get the current set of SDL memory functions.

Thread safety
This does not hold a lock, so do not call this in the unlikely event of a background thread calling setMemoryFunctions simultaneously.
See also
setMemoryFunctions, getOriginalMemoryFunctions

sdl3-bindgen-sys notes

Expand
FFI safety
Unsafe foreign import of SDL_GetMemoryFunctions. The safe flavor is getMemoryFunctionsSafe .
C declaration
SDL_GetMemoryFunctions, defined at SDL3/SDL_stdinc.h 1547:34

Since: 3.2.0

getMemoryFunctionsSafe Source #

Arguments

:: Ptr SDL_malloc_func
malloc_func
filled with malloc function.
-> Ptr SDL_calloc_func
calloc_func
filled with calloc function.
-> Ptr SDL_realloc_func
realloc_func
filled with realloc function.
-> Ptr SDL_free_func
free_func
filled with free function.
-> IO () 

Get the current set of SDL memory functions.

Thread safety
This does not hold a lock, so do not call this in the unlikely event of a background thread calling setMemoryFunctions simultaneously.
See also
setMemoryFunctions, getOriginalMemoryFunctions

sdl3-bindgen-sys notes

Expand
FFI safety
Safe foreign import of SDL_GetMemoryFunctions. The unsafe flavor is getMemoryFunctions .
C declaration
SDL_GetMemoryFunctions, defined at SDL3/SDL_stdinc.h 1547:34

Since: 3.2.0

setMemoryFunctions Source #

Arguments

:: SDL_malloc_func
malloc_func
custom malloc function.
-> SDL_calloc_func
calloc_func
custom calloc function.
-> SDL_realloc_func
realloc_func
custom realloc function.
-> SDL_free_func
free_func
custom free function.
-> IO Bool 

Replace SDL's memory allocation functions with a custom set.

It is not safe to call this function once any allocations have been made, as future calls to free will use the new allocator, even if they came from an malloc made with the old one!

If used, usually this needs to be the first call made into the SDL library, if not the very first thing done at program startup time.

Returns
true on success or false on failure; call getError for more information.
Thread safety
It is safe to call this function from any thread, but one should not replace the memory functions once any allocations are made!
See also
getMemoryFunctions, getOriginalMemoryFunctions

sdl3-bindgen-sys notes

Expand
FFI safety
Unsafe foreign import of SDL_SetMemoryFunctions. The safe flavor is setMemoryFunctionsSafe : registration; replacement allocators run inside every later SDL call.
Scalars
The binding generation has mapped C scalars to native Haskell scalars for this function. Pointers and structs are untouched by this best-effort mapping. Higher-level bindings are expected to map structs and pointers as appropriate.
C declaration
SDL_SetMemoryFunctions, defined at SDL3/SDL_stdinc.h 1578:34

Since: 3.2.0

setMemoryFunctionsSafe Source #

Arguments

:: SDL_malloc_func
malloc_func
custom malloc function.
-> SDL_calloc_func
calloc_func
custom calloc function.
-> SDL_realloc_func
realloc_func
custom realloc function.
-> SDL_free_func
free_func
custom free function.
-> IO Bool 

Replace SDL's memory allocation functions with a custom set.

It is not safe to call this function once any allocations have been made, as future calls to free will use the new allocator, even if they came from an malloc made with the old one!

If used, usually this needs to be the first call made into the SDL library, if not the very first thing done at program startup time.

Returns
true on success or false on failure; call getError for more information.
Thread safety
It is safe to call this function from any thread, but one should not replace the memory functions once any allocations are made!
See also
getMemoryFunctions, getOriginalMemoryFunctions

sdl3-bindgen-sys notes

Expand
FFI safety
Safe foreign import of SDL_SetMemoryFunctions. The unsafe flavor is setMemoryFunctions : registration; replacement allocators run inside every later SDL call.
Scalars
The binding generation has mapped C scalars to native Haskell scalars for this function. Pointers and structs are untouched by this best-effort mapping. Higher-level bindings are expected to map structs and pointers as appropriate.
C declaration
SDL_SetMemoryFunctions, defined at SDL3/SDL_stdinc.h 1578:34

Since: 3.2.0

alignedAlloc Source #

Arguments

:: Word64
alignment
the alignment of the memory.
-> Word64
size
the size to allocate.
-> IO (Ptr Void) 

Allocate memory aligned to a specific alignment.

The memory returned by this function must be freed with alignedFree, not free.

If alignment is less than the size of void *, it will be increased to match that.

The returned memory address will be a multiple of the alignment value, and the size of the memory allocated will be a multiple of the alignment value.

Returns
a pointer to the aligned memory, or NULL if allocation failed.
Thread safety
It is safe to call this function from any thread.
See also
alignedFree

sdl3-bindgen-sys notes

Expand
FFI safety
Unsafe foreign import of SDL_aligned_alloc. The safe flavor is alignedAllocSafe .
Scalars
The binding generation has mapped C scalars to native Haskell scalars for this function. Pointers and structs are untouched by this best-effort mapping. Higher-level bindings are expected to map structs and pointers as appropriate.
C declaration
SDL_aligned_alloc, defined at SDL3/SDL_stdinc.h 1605:47

Since: 3.2.0

alignedAllocSafe Source #

Arguments

:: Word64
alignment
the alignment of the memory.
-> Word64
size
the size to allocate.
-> IO (Ptr Void) 

Allocate memory aligned to a specific alignment.

The memory returned by this function must be freed with alignedFree, not free.

If alignment is less than the size of void *, it will be increased to match that.

The returned memory address will be a multiple of the alignment value, and the size of the memory allocated will be a multiple of the alignment value.

Returns
a pointer to the aligned memory, or NULL if allocation failed.
Thread safety
It is safe to call this function from any thread.
See also
alignedFree

sdl3-bindgen-sys notes

Expand
FFI safety
Safe foreign import of SDL_aligned_alloc. The unsafe flavor is alignedAlloc .
Scalars
The binding generation has mapped C scalars to native Haskell scalars for this function. Pointers and structs are untouched by this best-effort mapping. Higher-level bindings are expected to map structs and pointers as appropriate.
C declaration
SDL_aligned_alloc, defined at SDL3/SDL_stdinc.h 1605:47

Since: 3.2.0

alignedFree Source #

Arguments

:: Ptr Void
mem
a pointer previously returned by alignedAlloc, or NULL.
-> IO () 

Free memory allocated by alignedAlloc.

The pointer is no longer valid after this call and cannot be dereferenced anymore.

If mem is NULL, this function does nothing.

Thread safety
It is safe to call this function from any thread.
See also
alignedAlloc

sdl3-bindgen-sys notes

Expand
FFI safety
Unsafe foreign import of SDL_aligned_free. The safe flavor is alignedFreeSafe .
C declaration
SDL_aligned_free, defined at SDL3/SDL_stdinc.h 1623:34

Since: 3.2.0

alignedFreeSafe Source #

Arguments

:: Ptr Void
mem
a pointer previously returned by alignedAlloc, or NULL.
-> IO () 

Free memory allocated by alignedAlloc.

The pointer is no longer valid after this call and cannot be dereferenced anymore.

If mem is NULL, this function does nothing.

Thread safety
It is safe to call this function from any thread.
See also
alignedAlloc

sdl3-bindgen-sys notes

Expand
FFI safety
Safe foreign import of SDL_aligned_free. The unsafe flavor is alignedFree .
C declaration
SDL_aligned_free, defined at SDL3/SDL_stdinc.h 1623:34

Since: 3.2.0

getNumAllocations :: IO Int32 Source #

Get the number of outstanding (unfreed) allocations.

Returns
the number of allocations or -1 if allocation counting is disabled.
Thread safety
It is safe to call this function from any thread.

sdl3-bindgen-sys notes

Expand
FFI safety
Unsafe foreign import of SDL_GetNumAllocations. The safe flavor is getNumAllocationsSafe .
Scalars
The binding generation has mapped C scalars to native Haskell scalars for this function. Pointers and structs are untouched by this best-effort mapping. Higher-level bindings are expected to map structs and pointers as appropriate.
C declaration
SDL_GetNumAllocations, defined at SDL3/SDL_stdinc.h 1635:33

Since: 3.2.0

getNumAllocationsSafe :: IO Int32 Source #

Get the number of outstanding (unfreed) allocations.

Returns
the number of allocations or -1 if allocation counting is disabled.
Thread safety
It is safe to call this function from any thread.

sdl3-bindgen-sys notes

Expand
FFI safety
Safe foreign import of SDL_GetNumAllocations. The unsafe flavor is getNumAllocations .
Scalars
The binding generation has mapped C scalars to native Haskell scalars for this function. Pointers and structs are untouched by this best-effort mapping. Higher-level bindings are expected to map structs and pointers as appropriate.
C declaration
SDL_GetNumAllocations, defined at SDL3/SDL_stdinc.h 1635:33

Since: 3.2.0

getEnvironment :: IO (Ptr SDL_Environment) Source #

Get the process environment.

This is initialized at application start and is not affected by setenv() and unsetenv() calls after that point. Use setEnvironmentVariable and unsetEnvironmentVariable if you want to modify this environment, or sDL_setenv_unsafe or sDL_unsetenv_unsafe if you want changes to persist in the C runtime environment after quit.

Returns
a pointer to the environment for the process or NULL on failure; call getError for more information.
Thread safety
It is safe to call this function from any thread.
See also
getEnvironmentVariable, getEnvironmentVariables, setEnvironmentVariable, unsetEnvironmentVariable

sdl3-bindgen-sys notes

Expand
FFI safety
Unsafe foreign import of SDL_GetEnvironment. The safe flavor is getEnvironmentSafe .
C declaration
SDL_GetEnvironment, defined at SDL3/SDL_stdinc.h 1673:47

Since: 3.2.0

getEnvironmentSafe :: IO (Ptr SDL_Environment) Source #

Get the process environment.

This is initialized at application start and is not affected by setenv() and unsetenv() calls after that point. Use setEnvironmentVariable and unsetEnvironmentVariable if you want to modify this environment, or sDL_setenv_unsafe or sDL_unsetenv_unsafe if you want changes to persist in the C runtime environment after quit.

Returns
a pointer to the environment for the process or NULL on failure; call getError for more information.
Thread safety
It is safe to call this function from any thread.
See also
getEnvironmentVariable, getEnvironmentVariables, setEnvironmentVariable, unsetEnvironmentVariable

sdl3-bindgen-sys notes

Expand
FFI safety
Safe foreign import of SDL_GetEnvironment. The unsafe flavor is getEnvironment .
C declaration
SDL_GetEnvironment, defined at SDL3/SDL_stdinc.h 1673:47

Since: 3.2.0

createEnvironment Source #

Arguments

:: Bool
populated
true to initialize it from the C runtime environment, false to create an empty environment.
-> IO (Ptr SDL_Environment) 

Create a set of environment variables

Returns
a pointer to the new environment or NULL on failure; call getError for more information.
Thread safety
If populated is false, it is safe to call this function from any thread, otherwise it is safe if no other threads are calling setenv() or unsetenv()
See also
getEnvironmentVariable, getEnvironmentVariables, setEnvironmentVariable, unsetEnvironmentVariable, destroyEnvironment

sdl3-bindgen-sys notes

Expand
FFI safety
Unsafe foreign import of SDL_CreateEnvironment. The safe flavor is createEnvironmentSafe .
Scalars
The binding generation has mapped C scalars to native Haskell scalars for this function. Pointers and structs are untouched by this best-effort mapping. Higher-level bindings are expected to map structs and pointers as appropriate.
C declaration
SDL_CreateEnvironment, defined at SDL3/SDL_stdinc.h 1695:47

Since: 3.2.0

createEnvironmentSafe Source #

Arguments

:: Bool
populated
true to initialize it from the C runtime environment, false to create an empty environment.
-> IO (Ptr SDL_Environment) 

Create a set of environment variables

Returns
a pointer to the new environment or NULL on failure; call getError for more information.
Thread safety
If populated is false, it is safe to call this function from any thread, otherwise it is safe if no other threads are calling setenv() or unsetenv()
See also
getEnvironmentVariable, getEnvironmentVariables, setEnvironmentVariable, unsetEnvironmentVariable, destroyEnvironment

sdl3-bindgen-sys notes

Expand
FFI safety
Safe foreign import of SDL_CreateEnvironment. The unsafe flavor is createEnvironment .
Scalars
The binding generation has mapped C scalars to native Haskell scalars for this function. Pointers and structs are untouched by this best-effort mapping. Higher-level bindings are expected to map structs and pointers as appropriate.
C declaration
SDL_CreateEnvironment, defined at SDL3/SDL_stdinc.h 1695:47

Since: 3.2.0

getEnvironmentVariable Source #

Arguments

:: Ptr SDL_Environment
env
the environment to query.
-> PtrConst CChar
name
the name of the variable to get.
-> IO (PtrConst CChar) 

Get the value of a variable in the environment.

Returns
a pointer to the value of the variable or NULL if it can't be found.
Thread safety
It is safe to call this function from any thread.
See also
getEnvironment, createEnvironment, getEnvironmentVariables, setEnvironmentVariable, unsetEnvironmentVariable

sdl3-bindgen-sys notes

Expand
FFI safety
Unsafe foreign import of SDL_GetEnvironmentVariable. The safe flavor is getEnvironmentVariableSafe .
C declaration
SDL_GetEnvironmentVariable, defined at SDL3/SDL_stdinc.h 1715:42

Since: 3.2.0

getEnvironmentVariableSafe Source #

Arguments

:: Ptr SDL_Environment
env
the environment to query.
-> PtrConst CChar
name
the name of the variable to get.
-> IO (PtrConst CChar) 

Get the value of a variable in the environment.

Returns
a pointer to the value of the variable or NULL if it can't be found.
Thread safety
It is safe to call this function from any thread.
See also
getEnvironment, createEnvironment, getEnvironmentVariables, setEnvironmentVariable, unsetEnvironmentVariable

sdl3-bindgen-sys notes

Expand
FFI safety
Safe foreign import of SDL_GetEnvironmentVariable. The unsafe flavor is getEnvironmentVariable .
C declaration
SDL_GetEnvironmentVariable, defined at SDL3/SDL_stdinc.h 1715:42

Since: 3.2.0

getEnvironmentVariables Source #

Arguments

:: Ptr SDL_Environment
env
the environment to query.
-> IO (Ptr (Ptr CChar)) 

Get all variables in the environment.

Returns
a NULL terminated array of pointers to environment variables in the form "variable=value" or NULL on failure; call getError for more information. This is a single allocation that should be freed with free when it is no longer needed.
Thread safety
It is safe to call this function from any thread.
See also
getEnvironment, createEnvironment, getEnvironmentVariables, setEnvironmentVariable, unsetEnvironmentVariable

sdl3-bindgen-sys notes

Expand
FFI safety
Unsafe foreign import of SDL_GetEnvironmentVariables. The safe flavor is getEnvironmentVariablesSafe .
C declaration
SDL_GetEnvironmentVariables, defined at SDL3/SDL_stdinc.h 1736:37

Since: 3.2.0

getEnvironmentVariablesSafe Source #

Arguments

:: Ptr SDL_Environment
env
the environment to query.
-> IO (Ptr (Ptr CChar)) 

Get all variables in the environment.

Returns
a NULL terminated array of pointers to environment variables in the form "variable=value" or NULL on failure; call getError for more information. This is a single allocation that should be freed with free when it is no longer needed.
Thread safety
It is safe to call this function from any thread.
See also
getEnvironment, createEnvironment, getEnvironmentVariables, setEnvironmentVariable, unsetEnvironmentVariable

sdl3-bindgen-sys notes

Expand
FFI safety
Safe foreign import of SDL_GetEnvironmentVariables. The unsafe flavor is getEnvironmentVariables .
C declaration
SDL_GetEnvironmentVariables, defined at SDL3/SDL_stdinc.h 1736:37

Since: 3.2.0

setEnvironmentVariable Source #

Arguments

:: Ptr SDL_Environment
env
the environment to modify.
-> PtrConst CChar
name
the name of the variable to set.
-> PtrConst CChar
value
the value of the variable to set.
-> Bool
overwrite
true to overwrite the variable if it exists, false to return success without setting the variable if it already exists.
-> IO Bool 

Set the value of a variable in the environment.

Returns
true on success or false on failure; call getError for more information.
Thread safety
It is safe to call this function from any thread.
See also
getEnvironment, createEnvironment, getEnvironmentVariable, getEnvironmentVariables, unsetEnvironmentVariable

sdl3-bindgen-sys notes

Expand
FFI safety
Unsafe foreign import of SDL_SetEnvironmentVariable. The safe flavor is setEnvironmentVariableSafe .
Scalars
The binding generation has mapped C scalars to native Haskell scalars for this function. Pointers and structs are untouched by this best-effort mapping. Higher-level bindings are expected to map structs and pointers as appropriate.
C declaration
SDL_SetEnvironmentVariable, defined at SDL3/SDL_stdinc.h 1760:34

Since: 3.2.0

setEnvironmentVariableSafe Source #

Arguments

:: Ptr SDL_Environment
env
the environment to modify.
-> PtrConst CChar
name
the name of the variable to set.
-> PtrConst CChar
value
the value of the variable to set.
-> Bool
overwrite
true to overwrite the variable if it exists, false to return success without setting the variable if it already exists.
-> IO Bool 

Set the value of a variable in the environment.

Returns
true on success or false on failure; call getError for more information.
Thread safety
It is safe to call this function from any thread.
See also
getEnvironment, createEnvironment, getEnvironmentVariable, getEnvironmentVariables, unsetEnvironmentVariable

sdl3-bindgen-sys notes

Expand
FFI safety
Safe foreign import of SDL_SetEnvironmentVariable. The unsafe flavor is setEnvironmentVariable .
Scalars
The binding generation has mapped C scalars to native Haskell scalars for this function. Pointers and structs are untouched by this best-effort mapping. Higher-level bindings are expected to map structs and pointers as appropriate.
C declaration
SDL_SetEnvironmentVariable, defined at SDL3/SDL_stdinc.h 1760:34

Since: 3.2.0

unsetEnvironmentVariable Source #

Arguments

:: Ptr SDL_Environment
env
the environment to modify.
-> PtrConst CChar
name
the name of the variable to unset.
-> IO Bool 

Clear a variable from the environment.

Returns
true on success or false on failure; call getError for more information.
Thread safety
It is safe to call this function from any thread.
See also
getEnvironment, createEnvironment, getEnvironmentVariable, getEnvironmentVariables, setEnvironmentVariable, unsetEnvironmentVariable

sdl3-bindgen-sys notes

Expand
FFI safety
Unsafe foreign import of SDL_UnsetEnvironmentVariable. The safe flavor is unsetEnvironmentVariableSafe .
Scalars
The binding generation has mapped C scalars to native Haskell scalars for this function. Pointers and structs are untouched by this best-effort mapping. Higher-level bindings are expected to map structs and pointers as appropriate.
C declaration
SDL_UnsetEnvironmentVariable, defined at SDL3/SDL_stdinc.h 1781:34

Since: 3.2.0

unsetEnvironmentVariableSafe Source #

Arguments

:: Ptr SDL_Environment
env
the environment to modify.
-> PtrConst CChar
name
the name of the variable to unset.
-> IO Bool 

Clear a variable from the environment.

Returns
true on success or false on failure; call getError for more information.
Thread safety
It is safe to call this function from any thread.
See also
getEnvironment, createEnvironment, getEnvironmentVariable, getEnvironmentVariables, setEnvironmentVariable, unsetEnvironmentVariable

sdl3-bindgen-sys notes

Expand
FFI safety
Safe foreign import of SDL_UnsetEnvironmentVariable. The unsafe flavor is unsetEnvironmentVariable .
Scalars
The binding generation has mapped C scalars to native Haskell scalars for this function. Pointers and structs are untouched by this best-effort mapping. Higher-level bindings are expected to map structs and pointers as appropriate.
C declaration
SDL_UnsetEnvironmentVariable, defined at SDL3/SDL_stdinc.h 1781:34

Since: 3.2.0

destroyEnvironment Source #

Arguments

:: Ptr SDL_Environment
env
the environment to destroy.
-> IO () 

Destroy a set of environment variables.

Thread safety
It is safe to call this function from any thread, as long as the environment is no longer in use.
See also
createEnvironment

sdl3-bindgen-sys notes

Expand
FFI safety
Unsafe foreign import of SDL_DestroyEnvironment. The safe flavor is destroyEnvironmentSafe .
C declaration
SDL_DestroyEnvironment, defined at SDL3/SDL_stdinc.h 1795:34

Since: 3.2.0

destroyEnvironmentSafe Source #

Arguments

:: Ptr SDL_Environment
env
the environment to destroy.
-> IO () 

Destroy a set of environment variables.

Thread safety
It is safe to call this function from any thread, as long as the environment is no longer in use.
See also
createEnvironment

sdl3-bindgen-sys notes

Expand
FFI safety
Safe foreign import of SDL_DestroyEnvironment. The unsafe flavor is destroyEnvironment .
C declaration
SDL_DestroyEnvironment, defined at SDL3/SDL_stdinc.h 1795:34

Since: 3.2.0

strdup Source #

Arguments

:: PtrConst CChar
str
the string to copy.
-> IO (Ptr CChar) 

Allocate a copy of a string.

This allocates enough space for a null-terminated copy of str, using malloc, and then makes a copy of the string into this space.

The returned string is owned by the caller, and should be passed to free when no longer needed.

Returns
a pointer to the newly-allocated string.
Thread safety
It is safe to call this function from any thread.

sdl3-bindgen-sys notes

Expand
FFI safety
Unsafe foreign import of SDL_strdup. The safe flavor is strdupSafe .
C declaration
SDL_strdup, defined at SDL3/SDL_stdinc.h 3164:47

Since: 3.2.0

strdupSafe Source #

Arguments

:: PtrConst CChar
str
the string to copy.
-> IO (Ptr CChar) 

Allocate a copy of a string.

This allocates enough space for a null-terminated copy of str, using malloc, and then makes a copy of the string into this space.

The returned string is owned by the caller, and should be passed to free when no longer needed.

Returns
a pointer to the newly-allocated string.
Thread safety
It is safe to call this function from any thread.

sdl3-bindgen-sys notes

Expand
FFI safety
Safe foreign import of SDL_strdup. The unsafe flavor is strdup .
C declaration
SDL_strdup, defined at SDL3/SDL_stdinc.h 3164:47

Since: 3.2.0

strndup Source #

Arguments

:: PtrConst CChar
str
the string to copy.
-> Word64
maxlen
the maximum length of the copied string, not counting the null-terminator character.
-> IO (Ptr CChar) 

Allocate a copy of a string, up to n characters.

This allocates enough space for a null-terminated copy of str, up to maxlen bytes, using malloc, and then makes a copy of the string into this space.

If the string is longer than maxlen bytes, the returned string will be maxlen bytes long, plus a null-terminator character that isn't included in the count.

The returned string is owned by the caller, and should be passed to free when no longer needed.

Returns
a pointer to the newly-allocated string.
Thread safety
It is safe to call this function from any thread.

sdl3-bindgen-sys notes

Expand
FFI safety
Unsafe foreign import of SDL_strndup. The safe flavor is strndupSafe .
Scalars
The binding generation has mapped C scalars to native Haskell scalars for this function. Pointers and structs are untouched by this best-effort mapping. Higher-level bindings are expected to map structs and pointers as appropriate.
C declaration
SDL_strndup, defined at SDL3/SDL_stdinc.h 3189:47

Since: 3.2.0

strndupSafe Source #

Arguments

:: PtrConst CChar
str
the string to copy.
-> Word64
maxlen
the maximum length of the copied string, not counting the null-terminator character.
-> IO (Ptr CChar) 

Allocate a copy of a string, up to n characters.

This allocates enough space for a null-terminated copy of str, up to maxlen bytes, using malloc, and then makes a copy of the string into this space.

If the string is longer than maxlen bytes, the returned string will be maxlen bytes long, plus a null-terminator character that isn't included in the count.

The returned string is owned by the caller, and should be passed to free when no longer needed.

Returns
a pointer to the newly-allocated string.
Thread safety
It is safe to call this function from any thread.

sdl3-bindgen-sys notes

Expand
FFI safety
Safe foreign import of SDL_strndup. The unsafe flavor is strndup .
Scalars
The binding generation has mapped C scalars to native Haskell scalars for this function. Pointers and structs are untouched by this best-effort mapping. Higher-level bindings are expected to map structs and pointers as appropriate.
C declaration
SDL_strndup, defined at SDL3/SDL_stdinc.h 3189:47

Since: 3.2.0

stepUTF8 Source #

Arguments

:: Ptr (PtrConst CChar)
pstr
a pointer to a UTF-8 string pointer to be read and adjusted.
-> Ptr CSize
pslen
a pointer to the number of bytes in the string, to be read and adjusted. NULL is allowed.
-> IO Word32 

Decode a UTF-8 string, one Unicode codepoint at a time.

This will return the first Unicode codepoint in the UTF-8 encoded string in *pstr, and then advance *pstr past any consumed bytes before returning.

It will not access more than *pslen bytes from the string. *pslen will be adjusted, as well, subtracting the number of bytes consumed.

pslen is allowed to be NULL, in which case the string must be NULL-terminated, as the function will blindly read until it sees the NULL char.

if *pslen is zero, it assumes the end of string is reached and returns a zero codepoint regardless of the contents of the string buffer.

If the resulting codepoint is zero (a NULL terminator), or *pslen is zero, it will not advance *pstr or *pslen at all.

Generally this function is called in a loop until it returns zero, adjusting its parameters each iteration.

If an invalid UTF-8 sequence is encountered, this function returns SDL_INVALID_UNICODE_CODEPOINT and advances the string/length by one byte (which is to say, a multibyte sequence might produce several SDL_INVALID_UNICODE_CODEPOINT returns before it syncs to the next valid UTF-8 sequence).

Several things can generate invalid UTF-8 sequences, including overlong encodings, the use of UTF-16 surrogate values, and truncated data. Please refer to RFC3629 for details.

Returns
the first Unicode codepoint in the string.
Thread safety
It is safe to call this function from any thread.

sdl3-bindgen-sys notes

Expand
FFI safety
Unsafe foreign import of SDL_StepUTF8. The safe import is not exported : string computation over caller memory with no allocation; cannot block, lock, or call back.
Scalars
The binding generation has mapped C scalars to native Haskell scalars for this function. Pointers and structs are untouched by this best-effort mapping. Higher-level bindings are expected to map structs and pointers as appropriate.
C declaration
SDL_StepUTF8, defined at SDL3/SDL_stdinc.h 4030:36

Since: 3.2.0

stepBackUTF8 Source #

Arguments

:: PtrConst CChar
start
a pointer to the beginning of the UTF-8 string.
-> Ptr (PtrConst CChar)
pstr
a pointer to a UTF-8 string pointer to be read and adjusted.
-> IO Word32 

Decode a UTF-8 string in reverse, one Unicode codepoint at a time.

This will go to the start of the previous Unicode codepoint in the string, move *pstr to that location and return that codepoint.

If *pstr is already at the start of the string), it will not advance *pstr at all.

Generally this function is called in a loop until it returns zero, adjusting its parameter each iteration.

If an invalid UTF-8 sequence is encountered, this function returns SDL_INVALID_UNICODE_CODEPOINT.

Several things can generate invalid UTF-8 sequences, including overlong encodings, the use of UTF-16 surrogate values, and truncated data. Please refer to RFC3629 for details.

Returns
the previous Unicode codepoint in the string.
Thread safety
It is safe to call this function from any thread.

sdl3-bindgen-sys notes

Expand
FFI safety
Unsafe foreign import of SDL_StepBackUTF8. The safe import is not exported : string computation over caller memory with no allocation; cannot block, lock, or call back.
Scalars
The binding generation has mapped C scalars to native Haskell scalars for this function. Pointers and structs are untouched by this best-effort mapping. Higher-level bindings are expected to map structs and pointers as appropriate.
C declaration
SDL_StepBackUTF8, defined at SDL3/SDL_stdinc.h 4061:36

Since: 3.2.0

ucs4ToUTF8 Source #

Arguments

:: Word32
codepoint
a Unicode codepoint to convert to UTF-8.
-> Ptr CChar
dst
the location to write the encoded UTF-8. Must point to at least 4 bytes!
-> IO (Ptr CChar) 

Convert a single Unicode codepoint to UTF-8.

The buffer pointed to by dst must be at least 4 bytes long, as this function may generate between 1 and 4 bytes of output.

This function returns the first byte after the newly-written UTF-8 sequence, which is useful for encoding multiple codepoints in a loop, or knowing where to write a NULL-terminator character to end the string (in either case, plan to have a buffer of more than 4 bytes!).

If codepoint is an invalid value (outside the Unicode range, or a UTF-16 surrogate value, etc), this will use U+FFFD (REPLACEMENT CHARACTER) for the codepoint instead, and not set an error.

If dst is NULL, this returns NULL immediately without writing to the pointer and without setting an error.

Returns
the first byte past the newly-written UTF-8 sequence.
Thread safety
It is safe to call this function from any thread.

sdl3-bindgen-sys notes

Expand
FFI safety
Unsafe foreign import of SDL_UCS4ToUTF8. The safe import is not exported : string computation over caller memory with no allocation; cannot block, lock, or call back.
Scalars
The binding generation has mapped C scalars to native Haskell scalars for this function. Pointers and structs are untouched by this best-effort mapping. Higher-level bindings are expected to map structs and pointers as appropriate.
C declaration
SDL_UCS4ToUTF8, defined at SDL3/SDL_stdinc.h 4090:36

Since: 3.2.0

C shims

fourCC Source #

Arguments

:: Word8
a
the first ASCII character.
-> Word8
b
the second ASCII character.
-> Word8
c
the third ASCII character.
-> Word8
d
the fourth ASCII character.
-> IO Word32 

Define a four character code as a Uint32.

The SDL_FOURCC macro as a function.

Returns
the four characters converted into a Uint32, one character per-byte.
Thread safety
It is safe to call this function from any thread.

sdl3-bindgen-sys notes

Expand
FFI safety
Unsafe foreign import of lithon_SDL_FOURCC. The safe import is not exported : pure bit manipulation on immediate values; cannot block, lock, or call back.
Scalars
The binding generation has mapped C scalars to native Haskell scalars for this function. Pointers and structs are untouched by this best-effort mapping. Higher-level bindings are expected to map structs and pointers as appropriate.
C declaration
lithon_SDL_FOURCC, defined at sdl3-bindgen-sys/SDL_stdinc_shims.h 40:26

Since: 3.2.0