# 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]
)
```


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://aup.nomi.dev/built-in/c/apis.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.