← Index

x/type/ptr

Raw pointers (Ptr) and the foreign-function interface (Ffi): the FFI surface for C interop.

ns ptr/ffi are de-registered; low-level/hot callers fetch-and-cache the prims. int->ptr is ns int (Ptr from-int).

Class Ptr

(Ptr from-int n)

Construct a pointer from an integer address (the int->ptr cast).

Parameters:

• n : INTEGER — Integer address

Returns: POINTER — A pointer to that address

Examples:

(Ptr ->int (Ptr from-int 4096)) => 4096

(Ptr ptr? x)

Test whether a value is a raw pointer.

Parameters:

• x : ANY — Value to test

Returns: BOOL — True if x is a pointer

Examples:

(Ptr ptr? (Ptr from-int 0)) => #t
(Ptr ptr? 5) => #f

(Ptr ->int p)

The integer (address) representation of a pointer.

Parameters:

• p : POINTER — A pointer

Returns: INTEGER — Integer address

Examples:

(Ptr ->int (Ptr from-int 64)) => 64

(Ptr ->str p)

Copy the NUL-terminated C string at P into a fresh x-lang string.

Parameters:

• p : POINTER — A C string pointer

Returns: STRING — A new string (survives the C buffer)

Examples:

(Ptr ->str ((prim-ref 'str '->ptr) "hello")) => "hello"

(Ptr ref p off width)

Read a WIDTH-byte little-endian value at P+OFF.

Parameters:

• p : POINTER — Base pointer
• off : INTEGER — Byte offset
• width : INTEGER — Read width in bytes (1,2,4,8)

Returns: INTEGER — The value read

Examples:

(let ((p ((prim-ref 'str '->ptr) "AB"))) (Ptr ref p 1 1)) => 66

(Ptr set! p off v width)

Write a WIDTH-byte little-endian value V at P+OFF.

Parameters:

• p : POINTER — Base pointer
• off : INTEGER — Byte offset
• v : INTEGER — Value to store
• width : INTEGER — Write width in bytes

Returns: ANY — nil

Examples:

(let ((p ((prim-ref 'str '->ptr) ((prim-ref 'str 'make) 8)))) (Ptr set! p 0 200 1) (Ptr ref p 0 1)) => 200

(Ptr ref-word p off)

Read one machine word (sizeof(long)) at P+OFF.

Parameters:

• p : POINTER — Base pointer
• off : INTEGER — Byte offset

Returns: INTEGER — The word value

Examples:

(let ((p ((prim-ref 'str '->ptr) ((prim-ref 'str 'make) (* 2 %word-size))))) (Ptr set-word! p %word-size -7) (Ptr ref-word p %word-size)) => -7

(Ptr set-word! p off v)

Write one machine word V at P+OFF.

Parameters:

• p : POINTER — Base pointer
• off : INTEGER — Byte offset
• v : INTEGER — Word value to store

Returns: ANY — nil

Examples:

(let ((p ((prim-ref 'str '->ptr) ((prim-ref 'str 'make) %word-size)))) (Ptr set-word! p 0 12345) (Ptr ref-word p 0)) => 12345

(Ptr call p . args)

Call a C function pointer with string arguments.

Parameters:

• p : POINTER — C function pointer
• args : STRING — String arguments (variadic)

Returns: INTEGER — The C return value

Class Ffi

(Ffi dlopen path mode)

Load a shared library.

Parameters:

• path : STRING — Library file path (() for the main program)
• mode : INTEGER — dlopen mode flags (e.g. 1 = RTLD_LAZY)

Returns: POINTER — Library handle, or () on failure

Examples:

(null? (Ffi dlopen "/no/such/lib.so" 1)) => #t

(Ffi dlsym lib name)

Look up a symbol in a loaded library.

Parameters:

• lib : POINTER — Library handle from dlopen
• name : STRING — Symbol name

Returns: POINTER — Function or data pointer