> For the complete documentation index, see [llms.txt](https://aup.nomi.dev/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://aup.nomi.dev/built-in/c/apis.md).

# APIs

## .malloc

`C.malloc(size: num) -> ptr`

Allocate memory block

#### Parameters (1)

`size`

Size of memory block, in bytes.

#### Return value

On success, a pointer to the memory block allocated by the function.

If `size` is zero or the function failed to allocate the requested block of memory, `null` is returned.

## .calloc

`C.calloc(count: num, size: num) -> ptr`

Allocate and zero-initialize array

#### Parameters

`count`

Number of elements to allocate.

`size`

Size of each element.

#### Return value

Like `C.malloc`, but the returned memory block is zero-initialized.

## .realloc

`C.realloc(addr: ptr, size: num) -> ptr`

Reallocate memory block

#### Parameters (2)

`addr`

 Pointer to a memory block previously allocated with `C.malloc`, `C.calloc` or `C.realloc`.

If this is a null pointer, the function works like `C.malloc`.

`size`

* New size for the memory block, in bytes.

#### Return value

See `C.malloc`.

## .free

`C.free(addr: ptr)`

Deallocate memory block

#### Parameters (1)

`addr`

A block of memory previously allocated by a call to `C.malloc`, `C.calloc` or `C.realloc` is deallocated, making it available again for further allocations.

#### Return value

None.

{% hint style="info" %}
Must free pointers created by malloc, calloc and realloc to avoid memory leaks.
{% endhint %}

{% hint style="danger" %}
Do not free any pointer is freed or not formed by malloc, calloc and realloc.
{% endhint %}

## .memcpy

`C.memcpy(dest: ptr, src: ptr, size: num) -> ptr`

Copy one buffer to another.

#### Parameters (2)

#### Return value

Return `dest`.

## .memcmp

`C.memcmp(a: ptr, b: ptr, count: num) -> num`

Compares two buffers.

#### Parameters (2)

#### Return value

* Negative integer if `a` appears before `b` in lexicographical order.
* Zero if `a` and `b` compare equal, or `count` is zero.
* Positive integer if `a` appears after `b` in lexicographical order.

## .memset

`C.memset(dest: ptr, byte: num, count: num) -> ptr`

Fill the memory block by the given byte.

#### Parameters (3)

`dest`

Pointer to the object to fill.

`byte`

Fill byte, an integer number in range 0 - 255.

`count`

Number of bytes to fill.

#### Return

Return `dest`.

## .load

`dll.load(path: str) -> ptr`

Load a dynamic library (.dll, .so).

#### Parameters (1)

`path`

Path to file.

#### Return value

A handle in `ptr` of loaded library.

If path is invalid, return `null`.

## .def

`C.def(lib: ptr, name: str, ret: num, args: num[]) -> fn`

Create a function that wraps C API function.

#### Parameters (4)

`lib`

Pointer of loaded library.

`name`

Name of exported function.

`ret`

C type of function return.

`args`

C type array of parameters.

#### Return value

If `lib` is null or invalid, return `null`.

If success, return a function.

#### Examples

Wrap **abs** function in **msvcrt.dll**

```go
var crt = C.load('msvcrt.dll')
var abs = C.def(crt, 'abs', C.INT, [C.INT])
puts abs(-5)  // 5
```

## .extern

`C.extern(lib: ptr, sym: str) -> ptr`

Get address of exported symbol in library.

#### Parameters (2)

`lib`

Pointer of loaded library.

`sym`

String of symbol.

#### Return value

Address pointer.

## .sizeof

`C.sizeof(type: num | ptr) -> num`

C **sizeof** equivalent.

#### Parameters (1)

`type`

A struct created by `C.struct` or C type.

#### Return value

Size of given type, in bytes.

If the given type is invalid, return zero.

## .cif

`C.cif(callback: fn, ret: num, args: num[]) -> ptr`

Create C API callback function from a given function.

#### Parameters (3)

`callback`

A function, except function created by `C.def()`.

`ret`

C type of return.

`args`

C type array of parameters.

#### Return value

Pointer to a created callback function.

#### Examples

Win32 window procedure.

```go
// Load user32
var user32 = C.load('user32.dll')

// LRESULT DefWindowProcA(HWND, UINT, WPARAM, LPARAM)
var DefWindowProc = C.def(
    user32, 'DefWindowProcA',
    C.PTR, [C.PTR, C.UINT, C.PTR, C.PTR]
)

// WNDPROC, like DefWindowProcA signature
var wndproc = C.cif(
    func(hwnd, msg, wparam, lparam) {
        // Process message
        return DefWindowProc(hwnd, msg, wparam, lparam)
    },
    C.PTR, [C.PTR, C.UINT, C.PTR, C.PTR]
)
```