OspreyForth-Specific Features

OspreyForth has the following commands incorporated into the interpreter. You can find the code for these commands in the file pfcustom.c in the csrc folder

c:str:create ( str count -- cstring )
Creates a C-style string from a Forth string. Also takes advantage for entities.c by Christoph Gärtner which allows using HTML and XML entities as a placeholder for UTF-8 and control characters. See csrc/entities.c for a complete list

• Example: s" Test String" c:str:create
• Example: s" G$auml;rtner" c:str:create
  • The resulting C string is: "Gärtner"
  • Note: Two additions were made to the list: &ofthcrlf; and &ofthlf;. These insert "\r\n" and "\n" respectively.
  • More entities are expected to be added as time goes on.

c:mem:free ( cstring -- )
This can be used to free memory, usually associated with a C string

• Example: (assuming a pointer is on the stack) c:mem:free

c:str:length ( cstring -- cstring count )
This puts a number on the stack indicating the number of characters in a C string. Once this is done, the OspreyForth interpreter can print out the string using the usual Forth methods (although Forth does not recognize the "\0" delmiter, which is why the count is needed)

• Example: (assuming a c-string is on the stack) c:str:length

dynlib:open ( str count -- libptr )
Given a Forth string indicating the location of a dynamic library and the attendant string count, dynlib:open will attempt to locate and load a dynamic library.

• Example: s" /usr/share/somelib" dynlib:open
  • (as one would expect, s" " creates the string and the character count)

dynlib:close ( libptr -- resultcode )
Given a pointer on the stack, dynlib:close will try to unload the pointer and will deliver a status code of 0 if successful or -1 otherwise

• Example: (assuming a pointer is on the stack) dynlib:close

dynlib:error ( -- 0 ) or ( -- cstring count )
If something goes wrong with loading the dynamic library, dynlib:error can be used to check if there is an error message. If 0 is returned, nothing registered an error. If something did register an error, dynlib:error will leave a C string and a count for the interpreter to display.

• Example: dynlib:error

dynlib:sym ( str count libptr -- 0 ) or ( str count libptr -- funcptr )
This will retrieve a function pointer from a loaded library. If it successful, it will return a function pointer to call

• Example: s" cputs" (libc pointer) dynlib:sym
  • (as one would expect, s" " creates the string and the character count)

ffi:type:select ( number -- typeptr )
For dynamic library functions to be called, OspreyForth must use LibFFI's type functions. Given a number between 0 and 20, ffi:type:select will return a pointer for one of a series of different defined types. 0 will actually return a pointer to ffi_type_void, which should only be used for return values from a function.

• Example: 7 ffi:type:select
  • (this will return a pointer to ffi_type_uint64)

ffi:function:call ( libptr cstring number number -- )
This function assembles and calls a foreign (C language) interface. It's important to understand that arguments in the function signature are not the full set of arguments to use in a given function call. The arguments listed are only there to tell the function what to pull off the stack to complete a function call. For a complete example, see the file named "call_puts.fth"