diff --git a/README.md b/README.md index 72b52e8..c4f68db 100644 --- a/README.md +++ b/README.md @@ -28,7 +28,7 @@ How do I use it? Example: ``` - system: aString +system: aString "Some kind of comment" @@ -42,31 +42,29 @@ Then comes the so called pragma that describes the C function to call: ``` ``` -Function specification: - - should be the first line in the method - - enclosed in angle brackets: < > containing: - 1. Calling Convention, either apicall: (Pascal convention) or cdecl: (C convention) - - Mac - use either one - - Unix - use cdecl - - Windows - use apical - 2. Return Type (see types) - 3. External Function Name (literal string) - 4. Argument Types (a literal array) - 5. Module - "module: " + [filename of the external library (literal string)] (see below). +Function specification should be the first line in the method and enclosed in angle brackets: < > containing: +1. Calling Convention, either apicall: (Pascal convention) or cdecl: (C convention) + - Mac - use either one + - Unix - use cdecl + - Windows - use apical +2. Return Type (see types) +3. External Function Name (literal string) +4. Argument Types (a literal array) +5. Module - "module: " + [filename of the external library (literal string)] (see below). ``` ^self externalCallFailed. ``` -Failure handler - - normal smalltalk code - - executed if the linking to or calling the external function fails - - API calls don't know how to communicate failure like Squeak primitives do, so: - - it does not tell you whether the external function succeeded - - the most common code is simply '^self externalCallFailed.' +Failure handler: -Argument Types - - must be names of ExternalTypes, either: +* normal smalltalk code +* executed if the linking to or calling the external function fails +* API calls don't know how to communicate failure like Squeak primitives do, so: + * it does not tell you whether the external function succeeded + * the most common code is simply '^self externalCallFailed.' + +Argument Types must be names of ExternalTypes, either: - atomic types (see ExternalType class>>initializeFFIConstants and ExternalType class>>initializeAtomicTypes): void bool @@ -84,19 +82,17 @@ Argument Types double (double-precision float) Structure Types [4] - - subclass of ExternalStructure - - class>>fields that returns an array of field descriptions (see below) - - Example: - fields - ^#((red 'byte')(green 'byte')(blue 'byte')) - - class>>initialize which includes "self defineFields" (which must be -called before using the class) - - refer to as MyExternalStructure* (to indicate that the argument or return is a pointer to that structure) +* subclass of ExternalStructure +* class>>fields that returns an array of field descriptions (see below), example: + fields + ^#((red 'byte')(green 'byte')(blue 'byte')) +* class>>initialize which includes "self defineFields" (which must be called before using the class) +* refer to as MyExternalStructure* (to indicate that the argument or return is a pointer to that structure) Field description [4] - - 2-element array (or three but that does something else, I'm not sure what): - - first element is the field name - - second is the type +* 2-element array (or three but that does something else, I'm not sure what): + * first element is the field name + * second is the type Module Name - depends on the platform @@ -108,29 +104,27 @@ Module Name - For Classic applications, use 'InterfaceLib' - For Carbon libs, use 'CarbonLib' -Module Location - where the external library file lives - - depends on the platform - - Mac - - pre Snow Leopard - - checks VM path and common library paths - - Snow Leopard - - only looks in VM bundle's Resources file, you must either [5]: - - store all external libraries there - - ln -s path/to/library path/to/VM/Resources/library_name - - Change the VM's Info.plist "SqueakPluginsBuiltInOrLocalOnly" key from "true" to "false." +Module Location, where the external library file lives +- depends on the platform + - Mac + - pre Snow Leopard + - checks VM path and common library paths + - Snow Leopard + - only looks in VM bundle's Resources file, you must either [5]: + - store all external libraries there + - ln -s path/to/library path/to/VM/Resources/library_name + - Change the VM's Info.plist "SqueakPluginsBuiltInOrLocalOnly" key from "true" to "false." Caveats - - security - - malicious users could call arbitrary functions in the OS e.g. "format c:" from "system.dll" [7] - - VMs do not protect against buffer overflow from bad parameters [8]: - "this would require an attacker to execute arbitrary Smalltalk - code on your server. Of course if they can do that they own you - anyway, especially if you allow FFi or use the OSProcess plugin" - John McIntosh +- security + - malicious users could call arbitrary functions in the OS e.g. "format c:" from "system.dll" [7] + - VMs do not protect against buffer overflow from bad parameters [8]: + "this would require an attacker to execute arbitrary Smalltalk + code on your server. Of course if they can do that they own you + anyway, especially if you allow FFi or use the OSProcess plugin" - John McIntosh * difficulty - - if you make a mistake you'll not drop into the debugger but Squeak will -just crash [2] - - If you crash Squeak when it is running the garbage collector, then you -know your FFI code is leaking bits into object memory [2] + - if you make a mistake you'll not drop into the debugger but Squeak will just crash [2] + - If you crash Squeak when it is running the garbage collector, then you know your FFI code is leaking bits into object memory [2] What do I need to use FFI with Squeak?