7.0. C Interface Utilities

7.0.0. Libc Interface

this provides an interface to several commonly used functions from the standard C library. (malloc n)

malloc n bytes of memory and return a gptr to it. (free p)

free malloc'ed memory area pointed to by gptr p . (memcpy dest src size)

copies size bytes from memory pointed to by src to memory pointed to by dst , both of which must be gptr . The function returns nil. (little-endianp)

return t if the CPU is little endian (e.g. x86). and nil if it is not little endian (like sparcs). (testbit v b)

test if bit b of integer v is on. b must be between 0 and 31.

7.0.1. Control Structures

A few macros that can be used as control structures in compiled code. (icfor (i begin end step) l1 [l2...])

a C-like for loop with integer loop variable. i is a lisp symbol used as a loop variable, begin end and step must be numerical expression. They are all converted to int. This is equivalent to the C construct:
 for (int i = begin; i<end; i++) { .... }

This is macro that generates inline C, and can therefore only be called in compiled code.

7.0.2. Pointer Manipulation/Dereferencing
(lsh/libc/libc.lsh) (gptr+ p n)

add n to generic pointer p . The returned pointer points n bytes higher than p . (gptr- p1 p2)

returns the distance between two pointers (in bytes). (ptr-str g)

returns a string from a generic pointer to a zero terminated sequence of characters. (str-ptr s)

return a generic pointer to the data of string s (i.e. a pointer to a C-style null-terminated string). This must be used with caution because the data pointed to by the pointer may be garbage collected. (idx-ptr idx)
[DX] (lsh/libc/libc.lsh)

return a gptr that points to the first element of m . This must be used with caution because the data pointed to by the pointer may be garbage collected (when m is destroyed), or even displaced (when m is resized). idx-ptr is primarily used when calling C function that require a pointer to numerical data. Peek/Poke/Sizeof

A number of functions are provided to dereference pointers to various numerical types and either get the value they point to, or set the value at the address they point to. They are of the form:
 (peek-TYPE <ptr>)
 (poke-TYPE <ptr> <value>)

where TYPE can be any Lush numerical type (ubyte, short, int, float, double, gptr). The first form returns the value pointed to by ptr , while the second form sets the value. Another set of functions, (sizeof-TYPE) returns the size of the corresponding type.

These function are useful for accessing values in a pre-existing C structure (allocated by a C function). Creating a numerical variable from Lush is better done by first creating an idx0 of the appropriate type, and then getting a pointer to the data through idx-ptr . Example:

(setq z (double-matrix))
(my-c-function-that-takes-a-ptr-to-a-double (idx-ptr z)) (peek-ubyte s)
(lsh/libc/libc.lsh) (poke-ubyte s v)
(lsh/libc/libc.lsh) (sizeof-ubyte)
(lsh/libc/libc.lsh) (peek-short s)
(lsh/libc/libc.lsh) (poke-short s v)
(lsh/libc/libc.lsh) (sizeof-short)
(lsh/libc/libc.lsh) (peek-int s)
(lsh/libc/libc.lsh) (poke-int s v)
(lsh/libc/libc.lsh) (sizeof-int)
(lsh/libc/libc.lsh) (peek-float s)
(lsh/libc/libc.lsh) (poke-float s v)
(lsh/libc/libc.lsh) (sizeof-float)
(lsh/libc/libc.lsh) (peek-double s)
(lsh/libc/libc.lsh) (poke-double s v)
(lsh/libc/libc.lsh) (sizeof-double)
(lsh/libc/libc.lsh) (peek-gptr s)
(lsh/libc/libc.lsh) (poke-gptr s v)
(lsh/libc/libc.lsh) (sizeof-gptr)