CTypes¶

Usage

use CTypes;

or

import CTypes;

Defines C types and related routines to support interoperability.

This module provides access to common C types for the purpose of calling between Chapel and C, declaring variables using C’s types, etc. It also contains routines in support of working with C types.

See C Interoperability, and Interoperability for additional information about interoperating between Chapel and C (or other languages).

type c_int = integral¶: The Chapel type corresponding to the C ‘int’ type

type c_uint = integral¶: The Chapel type corresponding to the C ‘uint’ type

type c_long = integral¶: The Chapel type corresponding to the C ‘long’ type

type c_ulong = integral¶: The Chapel type corresponding to the C ‘unsigned long’ type

type c_longlong = integral¶: The Chapel type corresponding to the C ‘long long’ type

type c_ulonglong = integral¶: The Chapel type corresponding to the C ‘unsigned long long’ type

type c_char = integral¶: The Chapel type corresponding to the C ‘char’ type

type c_schar = integral¶: The Chapel type corresponding to the C ‘signed char’ type

type c_uchar = integral¶: The Chapel type corresponding to the C ‘unsigned char’ type

type c_short = integral¶: The Chapel type corresponding to the C ‘short’ type

type c_ushort = integral¶: The Chapel type corresponding to the C ‘unsigned short’ type

type c_intptr = integral¶: The Chapel type corresponding to the C ‘intptr_t’ type

type c_uintptr = integral¶: The Chapel type corresponding to the C ‘uintptr_t’ type

type c_ptrdiff = integral¶: The Chapel type corresponding to the C ‘ptrdiff_t’ type

type c_size_t = integral¶: The Chapel type corresponding to the C ‘size_t’ type

type c_ssize_t = integral¶: The Chapel type corresponding to the C ‘ssize_t’ type

type c_float = real(32)¶: The Chapel type corresponding to the C ‘float’ type

type c_double = real(64)¶: The Chapel type corresponding to the C ‘double’ type

type c_void_ptr = chpl__c_void_ptr¶: A Chapel type alias for void* in C. Casts from integral types to c_void_ptr as well as casts from c_void_ptr to integral types are supported and behave similarly to those operations in C.

proc c_nil¶: A Chapel version of a C NULL pointer.

proc is_c_nil(x): bool¶

Returns: true if the passed value is a NULL pointer (ie 0).

class c_ptr¶

Represents a local C pointer for the purpose of C integration. This class represents the equivalent to a C language pointer. Instances of this class support assignment to other instances or nil, == or != comparison with a c_void_ptr or with nil, and casting to another c_ptr type or to the c_void_ptr type.

As with a Chapel class, a c_ptr can be tested non-nil simply by including it in an if statement conditional, like so:

var x: c_ptr = c_ptrTo(...);
if x then do writeln("x is not nil");
if !x then do writeln("x is nil");

Additionally, a c_ptr can be output like so:

var x: c_ptr = c_ptrTo(...);
writeln(x); // outputs nil or e.g. 0xabc123000000

type eltType¶: The type that this pointer points to

proc this(i: integral) ref¶: Retrieve the i’th element (zero based) from a pointer to an array. Does the equivalent of ptr[i] in C.

proc deref() ref¶: Get element pointed to directly by this pointer. If the pointer refers to an array, this will return ptr[0].

proc writeThis(ch) throws¶: Print this pointer

record c_array¶

This class represents a C array with fixed size. A variable of type c_array can coerce to a c_ptr with the same element type. In that event, the pointer will be equivalent to c_ptrTo(array[0]). A c_array behaves similarly to a homogeneous tuple except that its indices start at 0 and it is guaranteed to be stored in contiguous memory. A c_array variable has value semantics. Declaring one as a function local variable will create the array elements in the function’s stack. Assigning or copy initializing will result in copying the elements (vs resulting in two pointers that refer to the same elements). A nil c_array is not representable in Chapel.

type eltType¶: The array element type

param size¶: The fixed number of elements

proc init(type eltType, param size)¶

proc deinit()¶

proc ref this(i: integral) ref: eltType: Retrieve the i’th element (zero based) from the array. Does the equivalent of arr[i] in C. Includes bounds checking when such checks are enabled.

proc ref this(param i: integral) ref: eltType: As with the previous function, returns the i’th element (zero based) from the array. This one emits a compilation error if i is out of bounds.

proc writeThis(ch) throws¶: Print the elements

proc init=(other: c_array)¶

operator c_array. = (ref lhs: c_array, rhs: c_array): Copy the elements from one c_array to another. Raises an error at compile time if the array sizes or element types do not match.

operator =(ref lhs: c_ptr, ref rhs: c_array)¶

proc c_ptrTo(arr: [])¶

Returns a c_ptr to the elements of a non-distributed Chapel rectangular array. Note that the existence of this c_ptr has no impact on the lifetime of the array. The returned pointer will be invalid if the original array is freed or even reallocated. Domain assignment could make this c_ptr invalid.

Arguments: arr – the array for which a pointer should be returned
Returns: a pointer to the array’s elements

proc c_ptrTo(ref x: ?t): c_ptr(t)

Returns a c_ptr to any Chapel object. Note that the existence of the c_ptr has no impact of the lifetime of the object. In many cases the object will be stack allocated and could go out of scope even if this c_ptr remains.

Arguments: x – the by-reference argument to get a pointer to. The argument should not be an array or domain (there is a different overload for arrays). Records, class instances, integral, real, imag, and complex types are supported.
Returns: a pointer to the argument passed by reference

proc c_sizeof(type x): c_size_t¶

Return the size in bytes of a type, as with the C sizeof built-in.

Warning

This method is intended for C interoperability. To enhance flexibility, it is possible to request the sizes of Chapel types. However, be aware:

Chapel types are not necessarily stored in contiguous memory

Behavior of c_sizeof with Chapel types may change

Behavior given a Chapel class type is not well-defined

proc c_offsetof(type t, param fieldname: string): c_size_t¶

Return the offset of a field in a record.

Warning

This method is intended for C interoperability. To enhance flexibility, it is possible to request the offset of elements within a Chapel record. However, be aware:

Chapel types are not necessary stored in contiguous memory
Behavior of c_offsetof may change
Behavior given a Chapel class type field is not well-defined

proc c_calloc(type eltType, size: integral): c_ptr(eltType)¶

Allocate memory and initialize all bits to 0. Note that this simply zeros memory, it does not call Chapel initializers (it is meant for primitive types and C interoperability only.) This memory should eventually be freed with c_free.

Arguments

eltType – the type of the elements to allocate
size – the number of elements to allocate space for

Returns

a c_ptr(eltType) to allocated memory

proc c_malloc(type eltType, size: integral): c_ptr(eltType)¶

Allocate memory that is not initialized. This memory should eventually be freed with c_free.

Arguments

eltType – the type of the elements to allocate
size – the number of elements to allocate space for

Returns

a c_ptr(eltType) to allocated memory

proc c_aligned_alloc(type eltType, alignment: integral, size: integral): c_ptr(eltType)¶

Allocate aligned memory that is not initialized. This memory should be eventually freed with c_free.

This function is intended to behave similarly to the C17 function aligned_alloc.

Arguments

eltType – the type of the elements to allocate
alignment – the memory alignment of the allocation which must be a power of two and a multiple of c_sizeof(c_void_ptr).
size – the number of elements to allocate space for

Returns

a c_ptr(eltType) to allocated memory

proc c_free(data: c_void_ptr)¶

Free memory that was allocated with c_calloc or c_malloc.

Arguments: data – the c_ptr to memory that was allocated. Note that both c_ptr(t) and c_void_ptr can be passed to this argument.

proc isAnyCPtr(type t: c_ptr) param¶: Returns true if t is a c_ptr type or c_void_ptr.

proc c_memmove(dest: c_void_ptr, const src: c_void_ptr, n: integral)¶

Copies n potentially overlapping bytes from memory area src to memory area dest.

This is a simple wrapper over the C memmove() function.

Arguments

dest – the destination memory area to copy to
src – the source memory area to copy from
n – the number of bytes from src to copy to dest

proc c_memcpy(dest: c_void_ptr, const src: c_void_ptr, n: integral)¶

Copies n non-overlapping bytes from memory area src to memory area dest. Use c_memmove if memory areas do overlap.

This is a simple wrapper over the C memcpy() function.

Arguments

dest – the destination memory area to copy to
src – the source memory area to copy from
n – the number of bytes from src to copy to dest

proc c_memcmp(const s1: c_void_ptr, const s2: c_void_ptr, n: integral)¶

Compares the first n bytes of memory areas s1 and s2

This is a simple wrapper over the C memcmp() function.

Returns: returns an integer less than, equal to, or greater than zero if the first n bytes of s1 are found, respectively, to be less than, to match, or be greater than the first n bytes of s2.

proc c_memset(s: c_void_ptr, c: integral, n: integral)¶

Fill bytes of memory with a particular byte value.

This is a simple wrapper over the C memset() function.

Arguments

s – the destination memory area to fill
c – the byte value to use
n – the number of bytes of s to fill

Returns

s