Ypsilon API Reference

Summaries:
load-shared-object	Loads a shared object, and returns its handle
c-function	Transcribes a stub code—lambda expression—that calls a C foreign function
c-function/errno	Is similar to c-function, but it transcribes a stub code that returns two values
c-function/win32-lasterror	Is similar to c-function, but it transcribes a stub code that returns two values
lookup-shared-object	Returns an address corresponding to a symbol name in a shared object
make-cdecl-callout	Returns a closure that calls a foreign function using the __cdecl calling convention
make-cdecl-callback	Returns a C callback function pointer using the __cdecl calling convention
make-stdcall-callout	Is similar to make-cdecl-callout, but it uses the __stdcall calling convention
make-stdcall-callback	Is similar to make-cdecl-callback, but it uses the __stdcall calling convention
make-bytevector-mapping	Provides transparent access to an arbitrary memory block
bytevector-mapping?	Returns #t if its argument is a bytevector-mapping object, and otherwise returns #f
shared-object-errno	Is a parameter contains a copy of thread local errno value
shared-object-win32-lasterror	Is a parameter contains a copy of thread local win32 lasterror value
win32-error->string	Returns an error message string corresponding to a win32 error code
on-darwin	<constant>
on-linux	<constant>
on-freebsd	<constant>
on-openbsd	<constant>
on-posix	<constant>
on-windows	<constant>
on-ia32	<constant>
on-x64	<constant>
on-ppc32	<constant>
on-ppc64	<constant>

load-shared-object loads a shared object, and returns its handle.

syntax:
(load-shared-object) (load-shared-object filename) => <handle>

arguments:
filename:	<string>

notes:
load-shared-object returns the handle for the main program if filename is omitted.

> (import (rnrs) (ypsilon ffi))

> (load-shared-object)

3086820976

> (load-shared-object "libc.so.6") ; Ubuntu 9.04

3086481440

c-function transcribes a stub code—lambda expression—that calls a C foreign function. Ypsilon handles data conversion between C and Scheme.

syntax:
(c-function so-handle so-name return-type function-name (argument-type ...)) (c-function so-handle so-name return-type __cdecl function-name (argument-type ...)) (c-function so-handle so-name return-type __stdcall function-name (argument-type ...))

arguments:
so-handle: so-name: return-type: function-name: (argument-type ...):	<handle> <string> <symbol> <symbol> <subform>

__cdecl
__stdcall: —an optional calling convention declarator. The __stdcall declarator is ignored on that other than Windows platforms. The __cdecl is the default for all of platforms.

so-handle

—a value returned by load-shared-object.

so-name

—a value for informational purposes.

return-type

—a foreign function return type declarator. Valid declarators are listed below:

• short
• int
• long
• long-long
• int8_t
• int16_t
• int32_t
• int64_t: receives a corresponding type value from C.; returns an exact integer value to Scheme.
• char
• unsigned-short
• unsigned-int
• unsigned-long
• unsigned-long-long
• uint8_t
• uint16_t
• uint32_t
• uint64_t
• size_t
• void*: receives a corresponding type value from C.; returns a non-negative exact integer value to Scheme
• float
• double: receives a corresponding type value from C.; returns a flonum value to Scheme.
• bool: receives a corresponding type value from C.; returns 0 or 1 to Scheme.
• char*: receives a utf-8 null terminated string or NULL from C.; returns string or 0 to Scheme.
• void: receives no value from C.; returns an unspecified value to Scheme.

(argument-type ...)

—a list of foreign function argument type declarators, (char* int int) for an example. Valid declarators are listed below:

• char

• short

• int

• long

• long-long

• unsigned-short

• unsigned-int

• unsigned-long

• unsigned-long-long

• int8_t

• int16_t

• int32_t

• int64_t

• uint8_t

• uint16_t

• uint32_t

• uint64_t

• size_t

expects an exact integer value from Scheme.

passes it to C as a corresponding type value.

• float

• double

expects a real value from Scheme.

passes it to C as a IEEE floating point number.

• bool

expects an exact integer value from Scheme.

passes it to C as a bool.

• char*

expects a string or 0 from Scheme.

passes it to C as a utf-8 null terminated string, or NULL.

• void*

expects an exact integer value or a bytevector from Scheme.

passes it to C as a void*.

• '...'

indicates variadic arguments.

• [int]

expects a vector of exact integer values from Scheme.

passes it to C as an address of int vector (i.e. int*).

• [char*]

expects a vector of string from Scheme.

passes it to C as an address of char* vector (i.e. char**).

• (*[char*])

expects a vector of string from Scheme.

passes it to C as an address of pointer to char* vector (i.e. char***).

• (c-callback ...)

expects a Scheme procedure.

passes it to C as a C callback function pointer.

syntax:
(c-callback return-type (argument-type ...)) (c-callback return-type __cdecl (argument-type ...)) (c-callback return-type __stdcall (argument-type ...))

arguments:
return-type: (argument-type ...):	<symbol> <subform>

__cdecl
__stdcall: —an optional calling convention declarator. The __stdcall declarator is ignored on that other than Windows platforms. The __cdecl is the default for all of platforms.

return-type

—a foreign callback return type declarator. Valid declarators are listed below:

• char
• short
• int
• long
• long-long
• unsigned-short
• unsigned-int
• unsigned-long
• unsigned-long-long
• int8_t
• int16_t
• int32_t
• int64_t
• uint8_t
• uint16_t
• uint32_t
• uint64_t
• size_t
• void*: receives an exact integer value from Scheme.; returns it to C as a corresponding type value.
• float
• double: receives a real value from Scheme.; returns it to C as a corresponding type value.
• bool: receives an exact integer value from Scheme.; returns false to C if the value is 0, and otherwise returns true to C.
• void: receives no value from Scheme.; returns no value to C.

(argument-type ...)

—a list of foreign callback argument type declarators. Valid declarators are listed below:

• bool: expects a corresponding type value from C.; passes it to Scheme as 0 or 1.
• short
• int
• long
• long-long
• int8_t
• int16_t
• int32_t
• int64_t: expects a corresponding type value from C.; passes it to Scheme as an exact integer value.
• char
• unsigned-short
• unsigned-int
• unsigned-long
• unsigned-long-long
• uint8_t
• uint16_t
• uint32_t
• uint64_t
• size_t
• void*: expects a corresponding type value from C.; passes it to Scheme as a non-negative exact integer value.
• float
• double: expects a corresponding type value from C.; passes it to Scheme as a real value.

examples:
(import (rnrs) (ypsilon ffi)) ;; load GLUT library (define lib (load-shared-object "libglut.so.3")) ; Ubuntu 8.10 ;; void glutPositionWindow(int x, int y) (define glutPositionWindow (c-function lib "GLUT" void glutPositionWindow (int int))) ;; void glutMouseFunc(void (func)(int button, int state, int x, int y)) (define glutMouseFunc (c-function lib "GLUT" void glutMouseFunc ([c-callback void (int int int int)]))) ;; void glutAddMenuEntry(const char label, int value) ;; void glutMotionFunc(void (func)(int x, int y)) (let-syntax ((defun-glut ; with handy macro (syntax-rules () ((_ ret name args) (define name (c-function lib "GLUT" ret name args)))))) (defun-glut void glutAddMenuEntry (char int)) (defun-glut void glutMotionFunc ([c-callback void (int int)])))

c-function/errno is similar to c-function, but it transcribes a stub code that returns two values. The first is a C function return value, and the second is a captured errno value on return of the C function.

examples:
> (import (rnrs) (ypsilon ffi)) > (define lib (load-shared-object "libc.so.6")) ; Ubuntu 8.10 > (define strerror (c-function lib "libc" char* strerror (int))) > (define chdir (c-function/errno lib "libc" int chdir (char*))) > (chdir "/") #<values 0 0> ; success, errno is meaningless on success as in C. > (chdir "/tmp/non-exists/foo/bar") #<values -1 2> ; failure, errno is 2 (ENOENT on linux). > (define my-chdir ; define wrapper function (lambda (path) (let-values (((retval errno) (chdir path))) (when (< retval 0) (assertion-violation 'my-chdir (strerror errno) (list path retval errno)))))) > (my-chdir "/tmp/non-exists/foo/bar") error in my-chdir: No such file or directory irritants: ("/non-exist/foo/bar" -1 2)

c-function/win32-lasterror is similar to c-function, but it transcribes a stub code that returns two values. The first is a C function return value, and the second is a value that obtained by calling GetLastError() on return of the C function.

lookup-shared-object returns an address corresponding to a symbol name in a shared object.

syntax:
(lookup-shared-object so-handle so-symbol) => <address>

arguments:
so-handle: so-symbol:	<handle> <string> or <symbol>

examples:
> (import (rnrs) (ypsilon ffi)) > (define libc (load-shared-object "libc.so.6")) ; Ubuntu 8.10 > (lookup-shared-object libc 'puts) 1075667872 > (lookup-shared-object libc "strlen") 1075757712

make-cdecl-callout returns a closure that calls a foreign function using the __cdecl calling convention.

syntax:
(make-cdecl-callout return-type argument-types function-address) => <procedure>

arguments:
return-type: argument-types: function-address:	<symbol> <list> <address>

return-type

—a foreign function return type declarator. Valid declarators are listed below:

short, int, long, long-long, int8_t, int16_t, int32_t, int64_t, unsigned-short, unsigned-int, unsigned-long, unsigned-long-long, uint8_t, uint16_t, uint32_t, uint64_t, size_t, void*, float, double, bool, char*, and void

argument-types

—a list of foreign function argument type declarators. Valid declarators are listed below:

bool, short, int, long, long-long, unsigned-short, unsigned-int, unsigned-long, unsigned-long-long, int8_t, int16_t, int32_t, int64_t, uint8_t, uint16_t, uint32_t, uint64_t, size_t, float, double, char*, void*, [int], [char*], (*[char*]) and '...'

function-address

—a value returned by lookup-shared-object.

notes:
Refer c-function for details of declarators.

examples:
> (import (rnrs) (ypsilon ffi)) > (define libc (load-shared-object "libc.so.6")) ; Ubuntu 8.10 > (define strcmp ; int strcmp(const char s1, const char s2) (make-cdecl-callout 'int '(char* char*) (lookup-shared-object libc "strcmp"))) > (strcmp "foo" "bar") 1 > (strcmp "hello" "hello") 0

make-cdecl-callback returns a C callback function pointer using the __cdecl calling convention.

syntax:
(make-cdecl-callback return-type argument-types procedure) => <address>

arguments:
return-type: argument-types: procedure:	<symbol> <list> <procedure>

return-type

—a foreign callback return type declarator. Valid declarators are listed below:

short, int, long, long-long, unsigned-short, unsigned-int, unsigned-long, unsigned-long-long, int8_t, int16_t, int32_t, int64_t, uint8_t, uint16_t, uint32_t, uint64_t, size_t, void*, float, double, bool, and void

argument-types

—a list of foreign callback argument type declarators. Valid declarators are listed below:

bool short, int, long, long-long, unsigned-short, unsigned-int, unsigned-long, unsigned-long-long, int8_t, int16_t, int32_t, int64_t, uint8_t, uint16_t, uint32_t, uint64_t, size_t, void*, float, and double

procedure

—a callback procedure.

notes:
Refer c-function for details of declarators.

examples:
> (import (rnrs) (ypsilon ffi)) > (define my-expt (lambda (n1 n2) (expt n1 n2))) > (define callback (make-cdecl-callback 'int '(int int) my-expt)) > callback 150958158 ; function address > (define callout (make-cdecl-callout 'int '(int int) callback)) > callout #<closure 0x77927a20> ; wrapper closure > (callout 10 3) 1000 ;; -> (callout 10 3) [Scheme] ;; -> callback(10, 3) [C] ;; -> (my-expt 10 3) [Scheme] ;; 1000 [Scheme] ;; 1000 [C] ;; 1000 [Scheme]

make-stdcall-callout is similar to make-cdecl-callout, but it uses the __stdcall calling convention.

make-stdcall-callback is similar to make-cdecl-callback, but it uses the __stdcall calling convention.

make-bytevector-mapping provides transparent access to an arbitrary memory block.

syntax:
(make-bytevector-mapping address bytesize) => <bytevector-mapping>

arguments:
address: bytesize:	<address> <int>

The bytesize must be non-negative.

description:
make-bytevector-mapping returns a bytevector-mapping object that can be used as an ordinary bytevector. Its contents are mapped to the memory block within the range of address to (address + bytesize - 1).

notes:
Be aware that misuse of this procedure causes a fatal error, segmentation fault for an example.

examples:
> (import (rnrs) (ypsilon ffi)) > (define libc (load-shared-object "libc.so.6")) ; Ubuntu 8.10 > (define qsort (c-function libc "libc" void qsort (void* int int [c-callback int (void* void*)]))) > (define comp (lambda (a1 a2) (let ((n1 (bytevector-u32-native-ref (make-bytevector-mapping a1 4) 0)) (n2 (bytevector-u32-native-ref (make-bytevector-mapping a2 4) 0))) (cond ((= n1 n2) 0) ((> n1 n2) 1) (else -1))))) > (define nums (uint-list->bytevector '(10000 1000 10 100000 100) (native-endianness) 4)) > (bytevector->uint-list nums (native-endianness) 4) (10000 1000 10 100000 100) > (qsort nums 5 4 comp) > (bytevector->uint-list nums (native-endianness) 4) (10 100 1000 10000 100000)

bytevector-mapping? returns #t if its argument is a bytevector-mapping object, and otherwise returns #f.

syntax:
(bytevector-mapping? x) => <boolean>

arguments:
x:	<object>

shared-object-errno is a parameter contains a copy of thread local errno value.

syntax:
(shared-object-errno errno-value) => unspecified (shared-object-errno) => <int>

arguments:
errno-value:	<int>

The errno-value must be within the range [INT_MIN, INT_MAX].

description:
Ypsilon captures the thread local errno value for each return of a foreign C function call. An assignment to this parameter also changes the thread local errno value.

shared-object-win32-lasterror is a parameter contains a copy of thread local win32 lasterror value.

syntax:
(shared-object-win32-lasterror lasterror-value) => unspecified (shared-object-win32-lasterror) => <int>

arguments:
lasterror-value:	<int>

The lasterror-value must be within the range [INT32_MIN, UINT32_MAX].

description:
On Windows platforms, Ypsilon captures a win32 lasterror value by calling GetLastError() for each return of a foreign C function call. An assignment to this parameter also changes the win32 lasterror value by calling SetLastError().

notes:
Using this parameter on that other than Windows platforms causes an assertion violation.

win32-error->string returns an error message string corresponding to a win32 error code.

syntax:
(win32-error->string win32-error-code) => <string>

arguments:
win32-error-code:	<int>

The win32-error-code must be within the range [INT32_MIN, UINT32_MAX].

description:
On Windows platforms, this procedure uses FormatMessage() to get an error message from a system.

notes:
Using this procedure on that other than Windows platforms causes an assertion violation.

Each constant is defined to a boolean value. It can be used to determine a operating system.

• on-darwin: is #t if the operating system is Darwin (Mac OS X).
• on-linux: is #t if the operating system is Linux.
• on-freebsd: is #t if the operating system is FreeBSD.
• on-openbsd: is #t if the operating system is OpenBSD.
• on-posix: is #t if the operating system is either Darwin, Linux, FreeBSD, or OpenBSD.
• on-windows: is #t if the operating system is Windows.

Each constant is defined to a boolean value. It can be used to determine a CPU instruction set.

• on-ia32: is #t if the CPU instruction set is IA-32.
• on-x64: is #t if the CPU instruction set is Intel64 or AMD64.
• on-ppc32: is #t if the CPU instruction set is 32-bit PowerPC.
• on-ppc64: is #t if the CPU instruction set is 64-bit PowerPC.