ctypes

  • Revision slug: Mozilla/js-ctypes/js-ctypes_reference/ctypes
  • Revision title: ctypes
  • Revision id: 4195
  • Created:
  • Creator: Sheppy
  • Is current revision? No
  • Comment add StructType; 228 words added, 3 words removed

Revision Content

{{ gecko_minversion_header() }}

{{ draft() }}

Method overview

Library management

Library open(libSpec);

Data type declarations

CType ArrayType(type[, n])
CType FunctionType(abi, returnType, [argType1, ..., argTypeN])
CType PointerType(type)
CType StructType(name, fields)

Constants

ABI constants

These constants are used to specify the ABI used to call a native function in the library.

Constant Description
default_abi Corresponds to cdecl; standard libraries use this ABI.
stdcall_abi Used for calling Windows API functions.

Data type constants

Primitive types

These constants define the primitive data types that behave the same on all platforms.

Constant Description
int8_t Signed 8-bit integer.
uint8_t Unsigned 8-bit integer.
int16_t Signed 16-bit integer.
uint16_t Unsigned 16-bit integer.
int32_t Signed 32-bit integer.
uint32_t Unsigned 32-bit integer.
int64_t Signed 64-bit integer.
uint64_t Unsigned 64-bit integer.
float32_t 32-bit floating-point value.
float64_t 64-bit floating-point value.
Note: Some 64-bit values are outside the range of numeric values supported by JavaScript. Because of this, ctypes.int64 and ctypes.uint64 do not automatically convert to JavaScript numbers. Instead, they convert to objects of the wrapper types ctypes.Int64 and ctypes.UInt64, which are JavaScript objects rather than CData objects. See 64-bit integer objects for details.

Types that act like specific C types

These types are designed to work exactly like the corresponding type on the native platform.

Constant Description
bool A Boolean type that behaves like the corresponding C type on the platform.
short A short integer type that behaves like the corresponding C type on the platform.
unsigned_short An unsigned short integer type that behaves like the corresponding C type on the platform.
int An integer type that behaves like the int C type on the platform.
unsigned_int An unsigned integer type that behaves like the unsigned int C type on the platform.
long

A long integer type that behaves like the corresponding C type on the platform.

Note: This automatically converts to an Int64 JavaScript object on all platforms, since it's unknown whether this is a 32-bit or 64-bit value. This is done for compatibility's sake.
unsigned long

An unsigned long integer type that behaves like the corresponding C type on the platform.

Note: This automatically converts to a UInt64 JavaScript object on all platforms, since it's unknown whether this is a 32-bit or 64-bit value. This is done for compatibility's sake.
float A floating point value that behaves like the float type on the platform.
double A double-precision floating point value that behaves like the double type on the platform.

Character types

Character types are 8-bit values that behave like their C counterparts. They're similar to the int8_t and uint8_t types, except conversion is handled differently.

For example, ctypes.char.array(30)(str) converts the string str to UTF-8 and returns a new CData object of array type.

Constant Description
char

A character type that behaves like the char C type on the platform.

signed_char A signed character that behaves like the char type on the platform.
unsigned_char An unsigned character that behaves like the unsigned char type on the platform.

Types whose size varies depending on platform

Because it's unknown whether these values will be 32-bit or 64-bit, they are not automatically converted into JavaScript numbers. Instead, these convert into Int64 or UInt64 JavaScript objects; see 64-bit integer objects for details.

Constant Description
size_t A platform-dependent size type.
ssize_t A platform-dependent size type.
intptr_t A platform-dependent integer representation of a pointer.
uintptr_t A platform-dependent unsigned integer representation of a pointer.

JavaScript characters

16-bit C Unicode characters are handled by js-ctypes using the jschar type.

Constant Description
jschar A 16-bit unsigned character. This is different from uint16_t in that C jschar values are automatically converted into 1-character JavaScript strings. These are Unicode characters.

Special C types

These C types that have special meanings

Constant Description
void_t

The special C type void. This can only be used as a return value type.

Note: You must use void_t, not void, since void is a keyword in JavaScript.
voidptr_t The C type void *. This is a pointer to an indeterminate type of data.

Methods

ArrayType()

Declares an array pointer data type.

Note: Array types with zero elements are supported, since C allows them.
function array_ptr_t ArrayType(
  type[,
  n]
);
Parameters
type
The data type of the elements in the array. This can be one of the Data type constants, or any user-defined types.
n {{ optional_inline() }}
The number of elements in the array. If this isn't specified, the resulting array type is for one with unspecified length.
Return value

A new array pointer data type.

Exceptions thrown
RangeError
The size of the resulting array type, in bytes, can't be exactly represented both as a C size_t value and as a JavaScript Number.
TypeError
type was not a recognized data type, or the type.size was undefined.

FunctionType()

Creates a function pointer data type; this can be used to store pointers to a function matching a given signature.

function_ptr_t FunctionType(
  abi,
  returnType[,
  argType1, ..., argTypeN]
); 
Parameters
abi
The ABI used to call this function; see ABI constants.
returnType
The data type returned by the function. This can be one of the Data type constants, or any user-defined types.
argType1, ..., argTypeN
Zero or more data types for the arguments to the function.
Return value

A function pointer data type which can be used when declaring functions or other types, including structures.

The returned pointer corresponds to the C type returnType (*) (argType1, ... argTypeN).

Exceptions thrown
TypeError
If any of the data types are unknown, this exception is thrown.

open()

Opens a library, which may be specified either by pathname or {{ interface("nsILocalFile") }}.

Library open(
  libSpec
);
Parameters
libSpec
The native library to open, specified as either a pathname string or an {{ interface("nsILocalFile") }}.
Return value

A Library object representing the opened library.

PointerType()

Creates a new pointer type.

type_ptr_t PointerType(
  type
); 
Parameters
type
If this is a type (either a user-defined type or one of the Data type constants), the returned type is "pointer to type". If this is a string, the returned type is an opaque pointer type named "type".
Return value

A pointer data type which can be used when declaring functions or other types, including structures.

StructType()

Creates a new structure data type.

Note: Currently, there is no way to represent a packed structure; that is, one that in C is defined using #pragma pack.
struct_t StructType(
  name,
  fields
); 
Parameters
name
The name of the structure.
fields
An array of field descriptors. Each field is described using a name and a type, which can be a user-defined type or one of the Data type constants.
Return value

A data type representing the corresponding C struct.

Exceptions thrown
RangeError
The size of the structure, in bytes, can't be exactly represented both as a size_t and as a JavaScript number.
TypeError
name isn't a string, or one of the fields is of a type with undefined size.
Notes

The syntax of the fields list looks like this:

[ { fieldName1: type1 }, { fieldName2: type2 }, ... ]
Example

For example, the C tm structure would be declared like this:

const struct_tm = new ctypes.StructType('tm',
                                  [  {'tm_sec': ctypes.int},
                                     {'tm_min': ctypes.int},
                                     {'tm_hour': ctypes.int},
                                     ..
                                  ]);

See also

Revision Source

<p>{{ gecko_minversion_header() }}</p>
<p>{{ draft() }}</p>
<h2>Method overview</h2>
<h3>Library management</h3>
<table class="standard-table"> <tbody> <tr> <td><code>Library <a href="/en/js-ctypes/js-ctypes_reference/ctypes#open()" title="en/js-ctypes/js-ctypes reference/ctypes#open()">open</a>(libSpec);</code></td> </tr> </tbody>
</table>
<h3>Data type declarations</h3>
<table class="standard-table"> <tbody> <tr> <td><code>CType <a href="/en/js-ctypes/js-ctypes_reference/ctypes#ArrayType()" title="en/js-ctypes/js-ctypes reference/ctypes#ArrayType()">ArrayType</a>(type[, n])<br> </code></td> </tr> <tr> <td><code>CType</code><code> <a href="/en/js-ctypes/js-ctypes_reference/ctypes#FunctionType()" title="en/js-ctypes/js-ctypes reference/ctypes#FunctionType()">FunctionType</a>(abi, returnType, [argType1, ..., argTypeN])</code></td> </tr> <tr> <td><code>CType</code><code> <a href="/en/js-ctypes/js-ctypes_reference/ctypes#PointerType()" title="en/js-ctypes/js-ctypes reference/ctypes#PointerType()">PointerType</a>(type)</code></td> </tr> <tr> <td><code>CType <a href="/en/js-ctypes/js-ctypes_reference/ctypes#StructType()" title="en/js-ctypes/js-ctypes reference/ctypes#StructType()">StructType</a>(name, fields)</code></td> </tr> </tbody>
</table>
<h2>Constants</h2>
<h3>ABI constants</h3>
<p>These constants are used to specify the ABI used to call a native function in the library.</p>
<table class="standard-table"> <tbody> <tr> <td class="header">Constant</td> <td class="header">Description</td> </tr> <tr> <td><code>default_abi</code></td> <td>Corresponds to <code>cdecl</code>; standard libraries use this ABI.</td> </tr> <tr> <td><code>stdcall_abi</code></td> <td>Used for calling Windows API functions.</td> </tr> </tbody>
</table>
<h3>Data type constants</h3>
<h4>Primitive types</h4>
<p>These constants define the primitive data types that behave the same on all platforms.</p>
<table class="standard-table"> <tbody> <tr> <td class="header">Constant</td> <td class="header">Description</td> </tr> <tr> <td><code>int8_t</code></td> <td>Signed 8-bit integer.</td> </tr> <tr> <td><code>uint8_t</code></td> <td>Unsigned 8-bit integer.</td> </tr> <tr> <td><code>int16_t</code></td> <td>Signed 16-bit integer.</td> </tr> <tr> <td><code>uint16_t</code></td> <td>Unsigned 16-bit integer.</td> </tr> <tr> <td><code>int32_t</code></td> <td>Signed 32-bit integer.</td> </tr> <tr> <td><code>uint32_t</code></td> <td>Unsigned 32-bit integer.</td> </tr> <tr> <td><code>int64_t</code></td> <td>Signed 64-bit integer.</td> </tr> <tr> <td><code>uint64_t</code></td> <td>Unsigned 64-bit integer.</td> </tr> <tr> <td><code>float32_t</code></td> <td>32-bit floating-point value.</td> </tr> <tr> <td><code>float64_t</code></td> <td>64-bit floating-point value.</td> </tr> </tbody>
</table>
<div class="note"><strong>Note:</strong> Some 64-bit values are outside the range of numeric values supported by JavaScript. Because of this, <code>ctypes.int64</code> and <code>ctypes.uint64</code> do not automatically convert to JavaScript numbers. Instead, they convert to objects of the wrapper types <code>ctypes.Int64</code> and <code>ctypes.UInt64</code>, which are JavaScript objects rather than CData objects. See 64-bit integer objects for details.</div>
<h4>Types that act like specific C types</h4>
<p>These types are designed to work exactly like the corresponding type on the native platform.</p>
<table class="standard-table"> <tbody> <tr> <td class="header">Constant</td> <td class="header">Description</td> </tr> <tr> <td><code>bool</code></td> <td>A Boolean type that behaves like the corresponding C type on the platform.</td> </tr> <tr> <td><code>short</code></td> <td>A short integer type that behaves like the corresponding C type on the platform.</td> </tr> <tr> <td><code>unsigned_short</code></td> <td>An unsigned short integer type that behaves like the corresponding C type on the platform.</td> </tr> <tr> <td><code>int</code></td> <td>An integer type that behaves like the <code>int</code> C type on the platform.</td> </tr> <tr> <td><code>unsigned_int</code></td> <td>An unsigned integer type that behaves like the <code>unsigned int</code> C type on the platform.</td> </tr> <tr> <td><code>long</code></td> <td> <p>A long integer type that behaves like the corresponding C type on the platform.</p> <div class="note"><strong>Note:</strong> This automatically converts to an <code>Int64</code> JavaScript object on all platforms, since it's unknown whether this is a 32-bit or 64-bit value. This is done for compatibility's sake.</div> </td> </tr> <tr> <td><code>unsigned long</code></td> <td> <p>An unsigned long integer type that behaves like the corresponding C type on the platform.</p> <div class="note"><strong>Note:</strong> This automatically converts to a <code>UInt64</code> JavaScript object on all platforms, since it's unknown whether this is a 32-bit or 64-bit value. This is done for compatibility's sake.</div> </td> </tr> <tr> <td><code>float</code></td> <td>A floating point value that behaves like the <code>float</code> type on the platform.</td> </tr> <tr> <td><code>double</code></td> <td>A double-precision floating point value that behaves like the <code>double</code> type on the platform.</td> </tr> </tbody>
</table>
<h4>Character types</h4>
<p>Character types are 8-bit values that behave like their C counterparts. They're similar to the <code>int8_t</code> and <code>uint8_t</code> types, except conversion is handled differently.</p>
<p>For example, <code>ctypes.char.array(30)(str)</code> converts the string <code>str</code> to UTF-8 and returns a new <code>CData</code> object of array type.</p>
<table class="standard-table"> <tbody> <tr> <td class="header">Constant</td> <td class="header">Description</td> </tr> <tr> <td><code>char</code></td> <td> <p>A character type that behaves like the <code>char</code> C type on the platform.</p> </td> </tr> <tr> <td><code>signed_char</code></td> <td>A signed character that behaves like the <code>char</code> type on the platform.</td> </tr> <tr> <td><code>unsigned_char</code></td> <td>An unsigned character that behaves like the <code>unsigned char</code> type on the platform.</td> </tr> </tbody>
</table>
<h4>Types whose size varies depending on platform</h4>
<p>Because it's unknown whether these values will be 32-bit or 64-bit, they are not automatically converted into JavaScript numbers. Instead, these convert into Int64 or UInt64 JavaScript objects; see 64-bit integer objects for details.</p>
<table class="standard-table"> <tbody> <tr> <td class="header">Constant</td> <td class="header">Description</td> </tr> <tr> <td><code>size_t</code></td> <td>A platform-dependent size type.</td> </tr> <tr> <td><code>ssize_t</code></td> <td>A platform-dependent size type.</td> </tr> <tr> <td><code>intptr_t</code></td> <td>A platform-dependent integer representation of a pointer.</td> </tr> <tr> <td><code>uintptr_t</code></td> <td>A platform-dependent unsigned integer representation of a pointer.</td> </tr> </tbody>
</table>
<h4>JavaScript characters</h4>
<p>16-bit C Unicode characters are handled by js-ctypes using the <code>jschar</code> type.</p>
<table class="standard-table"> <tbody> <tr> <td class="header">Constant</td> <td class="header">Description</td> </tr> <tr> <td><code>jschar</code></td> <td>A 16-bit unsigned character. This is different from <code>uint16_t</code> in that C <code>jschar</code> values are automatically converted into 1-character JavaScript strings. These are Unicode characters.</td> </tr> </tbody>
</table>
<h4>Special C types</h4>
<p>These C types that have special meanings</p>
<table class="standard-table"> <tbody> <tr> <td class="header">Constant</td> <td class="header">Description</td> </tr> <tr> <td><code>void_t</code></td> <td> <p>The special C type <code>void</code>. This can only be used as a return value type.</p> <div class="note"><strong>Note:</strong> You must use <code>void_t</code>, not <code>void</code>, since <code>void</code> is a keyword in JavaScript.</div> </td> </tr> <tr> <td><code>voidptr_t</code></td> <td>The C type <code>void *</code>. This is a pointer to an indeterminate type of data.</td> </tr> </tbody>
</table>
<h2>Methods</h2>
<h3>ArrayType()</h3>
<p>Declares an array pointer data type.</p>
<div class="note"><strong>Note: </strong>Array types with zero elements are supported, since C allows them.</div>
<pre>function array_ptr_t ArrayType(
  type[,
  n]
);</pre>
<h6>Parameters</h6>
<dl> <dt><code>type</code></dt> <dd>The data type of the elements in the array. This can be one of the <a href="/en/js-ctypes/js-ctypes_reference/ctypes#Data_type_constants" title="en/js-ctypes/js-ctypes reference/ctypes#Data type constants">Data type constants</a>, or any user-defined types.</dd> <dt><code>n</code> {{ optional_inline() }}</dt> <dd>The number of elements in the array. If this isn't specified, the resulting array type is for one with unspecified length.</dd>
</dl>
<h6>Return value</h6>
<p>A new array pointer data type.</p>
<h6>Exceptions thrown</h6>
<dl> <dt>RangeError</dt> <dd>The size of the resulting array type, in bytes, can't be exactly represented both as a C <code>size_t</code> value and as a JavaScript <code><a href="/cn/Core_JavaScript_1.5_Reference/Global_Objects/Number" title="cn/Core JavaScript 1.5 Reference/Global Objects/Number">Number</a></code>.</dd> <dt><code>TypeError</code></dt> <dd><code>type</code> was not a recognized data type, or the <code>type.size</code> was undefined.</dd>
</dl>
<h3>FunctionType()</h3>
<p>Creates a function pointer data type; this can be used to store pointers to a function matching a given signature.</p>
<pre>function_ptr_t FunctionType(
  abi,
  returnType[,
  argType1, ..., argTypeN]
); 
</pre>
<h6>Parameters</h6>
<dl> <dt><code>abi</code></dt> <dd>The ABI used to call this function; see <a href="/en/js-ctypes/js-ctypes_reference/ctypes#ABI_constants" title="en/js-ctypes/js-ctypes reference/ctypes#ABI constants">ABI constants</a>.</dd> <dt><code>returnType</code></dt> <dd>The data type returned by the function. This can be one of the <a href="/en/js-ctypes/js-ctypes_reference/ctypes#Data_type_constants" title="en/js-ctypes/js-ctypes reference/ctypes#Data type constants">Data type constants</a>, or any user-defined types.</dd> <dt><code>argType1, ..., argTypeN</code></dt> <dd>Zero or more data types for the arguments to the function.</dd>
</dl>
<h6>Return value</h6>
<p>A function pointer data type which can be used when declaring functions or other types, including structures.</p>
<p>The returned pointer corresponds to the C type <code>returnType (*) (argType1, ... argTypeN)</code>.</p>
<h6>Exceptions thrown</h6>
<dl> <dt><code>TypeError</code></dt> <dd>If any of the data types are unknown, this exception is thrown.</dd>
</dl>
<h3 name="eatCookie.28.29">open()</h3>
<p>Opens a library, which may be specified either by pathname or {{ interface("nsILocalFile") }}.</p>
<pre class="eval">Library open(
  libSpec
);
</pre>
<h6 name="Parameters">Parameters</h6>
<dl> <dt><code>libSpec</code></dt> <dd>The native library to open, specified as either a pathname string or an {{ interface("nsILocalFile") }}.</dd>
</dl>
<h6>Return value</h6>
<p>A <a href="/en/js-ctypes/js-ctypes_reference/Library" title="en/js-ctypes/js-ctypes reference/Library"><code>Library</code></a> object representing the opened library.</p>
<h3>PointerType()</h3>
<p>Creates a new pointer type.</p>
<pre>type_ptr_t PointerType(
  type
); 
</pre>
<h6>Parameters</h6>
<dl> <dt><code>type</code></dt> <dd>If this is a type (either a user-defined type or one of the <a href="/en/js-ctypes/js-ctypes_reference/ctypes#Data_type_constants" title="en/js-ctypes/js-ctypes reference/ctypes#Data type constants">Data type constants</a>), the returned type is "pointer to type". If this is a string, the returned type is an opaque pointer type named "<code>type</code>".</dd>
</dl>
<h6>Return value</h6>
<p>A pointer data type which can be used when declaring functions or other types, including structures.</p>
<h2>StructType()</h2>
<p>Creates a new structure data type.</p>
<div class="note"><strong>Note:</strong> Currently, there is no way to represent a packed structure; that is, one that in C is defined using <code>#pragma pack</code>.</div>
<pre>struct_t StructType(
  name,
  fields
); 
</pre>
<h6>Parameters</h6>
<dl> <dt><code>name</code></dt> <dd>The name of the structure.</dd> <dt><code>fields</code></dt> <dd>An array of field descriptors. Each field is described using a name and a type, which can be a user-defined type or one of the <a href="/en/js-ctypes/js-ctypes_reference/ctypes#Data_type_constants" title="en/js-ctypes/js-ctypes reference/ctypes#Data type constants">Data type constants</a>.</dd>
</dl>
<h6>Return value</h6>
<p>A data type representing the corresponding C <code>struct</code>.</p>
<h6>Exceptions thrown</h6>
<dl> <dt><code>RangeError</code></dt> <dd>The size of the structure, in bytes, can't be exactly represented both as a <code>size_t</code> and as a JavaScript number.</dd> <dt><code>TypeError</code></dt> <dd><code>name</code> isn't a string, or one of the fields is of a type with undefined size.</dd> <h6>Notes</h6> <p>The syntax of the <code>fields</code> list looks like this:</p> <pre>[ { fieldName1: type1 }, { fieldName2: type2 }, ... ]
</pre> <h6>Example</h6> <p>For example, the C <code>tm</code> structure would be declared like this:</p> <pre class="brush: js">const struct_tm = new ctypes.StructType('tm',
                                  [  {'tm_sec': ctypes.int},
                                     {'tm_min': ctypes.int},
                                     {'tm_hour': ctypes.int},
                                     ..
                                  ]);</pre>
</dl>
<h2>See also</h2>
<ul> <li><a href="/en/JavaScript_code_modules/ctypes.jsm" title="en/JavaScript code modules/ctypes.jsm">ctypes.jsm</a></li> <li><a href="/en/js-ctypes/Using_js-ctypes" title="en/js-ctypes/Using js-ctypes">Using js-ctypes</a></li>
</ul>
Revert to this revision