Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with
or
.
Download ZIP
Newer
Older
100644 84 lines (58 sloc) 3.183 kB
ab0b75a @rbranson Tree (Re)organization; Added type aliases for common C types; StructT…
rbranson authored
1 # node-ffi
2
3 Rick Branson rick [at] diodeware [dot] com
4 http://github.com/rbranson/node-ffi
5
6 # DESCRIPTION
7
e855c88 @rbranson Added factorial C library example
rbranson authored
8 node-ffi is a Node.js addon for loading and calling dynamic libraries using pure JavaScript. It can be used to create bindings to native libraries without writing any C++ code.
9
e7d0691 @rbranson Spelling error in README
rbranson authored
10 It also simplifies the augmentation of node.js with C code as it takes care of handling the translation of types across JavaScript and C, which can add reams of boilerplate code to your otherwise simple C. See the `example/factorial` for an example of this use case.
ab0b75a @rbranson Tree (Re)organization; Added type aliases for common C types; StructT…
rbranson authored
11
12 WARNING: node-ffi assumes you know what you're doing. You can pretty easily create situations where you will segfault the interpreter and unless you've got C debugger skills, you probably won't know what's going on.
13
14 # EXAMPLE
15
16 var FFI = require("node-ffi");
17
18 var libm = new FFI.Library("libm", { "ceil": [ "double", [ "double" ] ] });
19 libm.ceil(1.5); // 2
20
21 // You can also access just functions in the current process by passing a null
22 var current = new FFI.Library(null, { "atoi": [ "int32", [ "string" ] ] });
23 current.atoi("1234"); // 1234
24
25 # REQUIREMENTS
26
27 * Linux, OS X, or Solaris.
ddba83d @rbranson Added struct nesting
rbranson authored
28 * You will need node.js 0.2.3+
5be3945 @rbranson Added Call Overhead info to README
rbranson authored
29 * libffi installed -- with development headers (comes with OS X and most Linux distros)
ab0b75a @rbranson Tree (Re)organization; Added type aliases for common C types; StructT…
rbranson authored
30
31 # NPM INSTALL
32
33 $ npm install node-ffi
34
35 # SOURCE INSTALL
36
37 $ git clone git://github.com/rbranson/node-ffi.git
38 $ cd node-ffi
39 $ node-waf configure build
40 $ node test.js
41 $ node-waf install
42
43 # TYPES
44
e6c42a4 @rbranson Fixed README spacing
rbranson authored
45 int8 Signed 8-bit Integer
46 uint8 Unsigned 8-bit Integer
47 int16 Signed 16-bit Integer
48 uint16 Unsigned 16-bit Integer
49 int32 Signed 32-bit Integer
50 uint32 Unsigned 32-bit Integer
51 int64 Signed 64-bit Integer
52 uint64 Unsigned 64-bit Integer
53 float Single Precision Floating Point Number (float)
54 double Double Precision Floating Point Number (double)
55 pointer Pointer Type
56 string Null-Terminated String (char *)
ab0b75a @rbranson Tree (Re)organization; Added type aliases for common C types; StructT…
rbranson authored
57
58 In addition to the basic types, there are type aliases for common C types.
59
e6c42a4 @rbranson Fixed README spacing
rbranson authored
60 byte unsigned char
61 char char
62 uchar unsigned char
63 short short
ab0b75a @rbranson Tree (Re)organization; Added type aliases for common C types; StructT…
rbranson authored
64 ushort unsigned short
e6c42a4 @rbranson Fixed README spacing
rbranson authored
65 int int
66 uint unsigned int
67 long long
68 ulong unsigned long
ab0b75a @rbranson Tree (Re)organization; Added type aliases for common C types; StructT…
rbranson authored
69 longlong long long
70 ulonglong unsigned long long
8f54311 @rbranson Added a test to make sure size_t types are unsigned
rbranson authored
71 size_t platform-dependent, usually pointer size
ab0b75a @rbranson Tree (Re)organization; Added type aliases for common C types; StructT…
rbranson authored
72
02b5f52 @rbranson 64-bit methods on Pointer now use strings
rbranson authored
73 # V8 and 64-bit Types
74
75 Internally, V8 stores integers that will fit into a 32-bit space in a 32-bit integer, and those that fall outside of this get put into double-precision floating point numbers. This is problematic because FP numbers are imprecise. To get around this, the methods in node-ffi that deal with 64-bit integers return strings and can accept strings as parameters.
76
5be3945 @rbranson Added Call Overhead info to README
rbranson authored
77 # Call Overhead
78
79 There is non-trivial overhead associated with FFI calls. Comparing a hard-coded binding version of `strtoul()` to an FFI version of `strtoul()` shows that the native hard-coded binding is 5x faster. So don't just use the C version of a function just because it's faster. There's a significant cost in FFI calls, so make them worth it.
80
ab0b75a @rbranson Tree (Re)organization; Added type aliases for common C types; StructT…
rbranson authored
81 # LICENSE
82
83 See LICENSE file.
Something went wrong with that request. Please try again.