C Interface¶
ccall
((symbol, library) or function_pointer, ReturnType, (ArgumentType1, ...), ArgumentValue1, ...)¶Call function in C-exported shared library, specified by
(functionname,library)
tuple, where each component is a string or symbol.Note that the argument type tuple must be a literal tuple, and not a tuple-valued variable or expression. Alternatively,
ccall
may also be used to call a function pointer, such as one returned bydlsym
.Each
ArgumentValue
to theccall
will be converted to the correspondingArgumentType
, by automatic insertion of calls tounsafe_convert(ArgumentType,cconvert(ArgumentType,ArgumentValue))
. (See also the documentation for each of these functions for further details.) In most cases, this simply results in a call toconvert(ArgumentType,ArgumentValue)
.
cglobal
((symbol, library)[, type=Void])¶Obtain a pointer to a global variable in a C-exported shared library, specified exactly as in
ccall
. Returns aPtr{Type}
, defaulting toPtr{Void}
if no Type argument is supplied. The values can be read or written byunsafe_load
orunsafe_store!
, respectively.
cfunction
(function::Function, ReturnType::Type, (ArgumentTypes...))¶Generate C-callable function pointer from Julia function. Type annotation of the return value in the callback function is a must for situations where Julia cannot infer the return type automatically.
For example:
function foo()# bodyretval::Float64endbar=cfunction(foo,Float64,())
unsafe_convert
(T, x)¶Convert
x
to a value of typeT
In cases where
convert
would need to take a Julia object and turn it into aPtr
, this function should be used to define and perform that conversion.Be careful to ensure that a Julia reference to
x
exists as long as the result of this function will be used. Accordingly, the argumentx
to this function should never be an expression, only a variable name or field reference. For example,x=a.b.c
is acceptable, butx=[a,b,c]
is not.The
unsafe
prefix on this function indicates that using the result of this function after thex
argument to this function is no longer accessible to the program may cause undefined behavior, including program corruption or segfaults, at any later time.
cconvert
(T, x)¶Convert
x
to a value of typeT
, typically by callingconvert(T,x)
In cases where
x
cannot be safely converted toT
, unlikeconvert
,cconvert
may return an object of a type different fromT
, which however is suitable forunsafe_convert
to handle.Neither
convert
norcconvert
should take a Julia object and turn it into aPtr
.
unsafe_load
(p::Ptr{T}, i::Integer)¶Load a value of type
T
from the address of the ith element (1-indexed) starting atp
. This is equivalent to the C expressionp[i-1]
.The
unsafe
prefix on this function indicates that no validation is performed on the pointerp
to ensure that it is valid. Incorrect usage may segfault your program or return garbage answers, in the same manner as C.
unsafe_store!
(p::Ptr{T}, x, i::Integer)¶Store a value of type
T
to the address of the ith element (1-indexed) starting atp
. This is equivalent to the C expressionp[i-1]=x
.The
unsafe
prefix on this function indicates that no validation is performed on the pointerp
to ensure that it is valid. Incorrect usage may corrupt or segfault your program, in the same manner as C.
unsafe_copy!
(dest::Ptr{T}, src::Ptr{T}, N)¶Copy
N
elements from a source pointer to a destination, with no checking. The size of an element is determined by the type of the pointers.The
unsafe
prefix on this function indicates that no validation is performed on the pointersdest
andsrc
to ensure that they are valid. Incorrect usage may corrupt or segfault your program, in the same manner as C.
unsafe_copy!
(dest::Array, do, src::Array, so, N)Copy
N
elements from a source array to a destination, starting at offsetso
in the source anddo
in the destination (1-indexed).The
unsafe
prefix on this function indicates that no validation is performed to ensure that N is inbounds on either array. Incorrect usage may corrupt or segfault your program, in the same manner as C.
copy!
(dest, src)¶Copy all elements from collection
src
to arraydest
. Returnsdest
.
copy!
(dest, do, src, so, N)Copy
N
elements from collectionsrc
starting at offsetso
, to arraydest
starting at offsetdo
. Returnsdest
.
pointer
(array[, index])¶Get the native address of an array or string element. Be careful to ensure that a Julia reference to
a
exists as long as this pointer will be used. This function is “unsafe” likeunsafe_convert
.Calling
Ref(array[,index])
is generally preferable to this function.
pointer_to_array
(pointer, dims[, take_ownership::Bool])¶Wrap a native pointer as a Julia Array object. The pointer element type determines the array element type.
own
optionally specifies whether Julia should take ownership of the memory, callingfree
on the pointer when the array is no longer referenced.
pointer_from_objref
(object_instance)¶Get the memory address of a Julia object as a
Ptr
. The existence of the resultingPtr
will not protect the object from garbage collection, so you must ensure that the object remains referenced for the whole time that thePtr
will be used.
unsafe_pointer_to_objref
(p::Ptr)¶Convert a
Ptr
to an object reference. Assumes the pointer refers to a valid heap-allocated Julia object. If this is not the case, undefined behavior results, hence this function is considered “unsafe” and should be used with care.
disable_sigint
(f::Function)¶Disable Ctrl-C handler during execution of a function, for calling external code that is not interrupt safe. Intended to be called using
do
block syntax as follows:disable_sigint()do# interrupt-unsafe code...end
reenable_sigint
(f::Function)¶Re-enable Ctrl-C handler during execution of a function. Temporarily reverses the effect of
disable_sigint
.
systemerror
(sysfunc, iftrue)¶Raises a
SystemError
forerrno
with the descriptive stringsysfunc
ififtrue
istrue
Ptr{T}
¶A memory address referring to data of type
T
. However, there is no guarantee that the memory is actually valid, or that it actually represents data of the specified type.
Ref{T}
¶An object that safely references data of type
T
. This type is guaranteed to point to valid, Julia-allocated memory of the correct type. The underlying data is protected from freeing by the garbage collector as long as theRef
itself is referenced.When passed as a
ccall
argument (either as aPtr
orRef
type), aRef
object will be converted to a native pointer to the data it references.There is no invalid (NULL)
Ref
.
Cchar
¶Equivalent to the native
char
c-type
Cuchar
¶Equivalent to the native
unsignedchar
c-type (UInt8)
Cshort
¶Equivalent to the native
signedshort
c-type (Int16)
Cushort
¶Equivalent to the native
unsignedshort
c-type (UInt16)
Cint
¶Equivalent to the native
signedint
c-type (Int32)
Cuint
¶Equivalent to the native
unsignedint
c-type (UInt32)
Clong
¶Equivalent to the native
signedlong
c-type
Culong
¶Equivalent to the native
unsignedlong
c-type
Clonglong
¶Equivalent to the native
signedlonglong
c-type (Int64)
Culonglong
¶Equivalent to the native
unsignedlonglong
c-type (UInt64)
Cintmax_t
¶Equivalent to the native
intmax_t
c-type (Int64)
Cuintmax_t
¶Equivalent to the native
uintmax_t
c-type (UInt64)
Csize_t
¶Equivalent to the native
size_t
c-type (UInt)
Cssize_t
¶Equivalent to the native
ssize_t
c-type
Cptrdiff_t
¶Equivalent to the native
ptrdiff_t
c-type (Int)
Coff_t
¶Equivalent to the native
off_t
c-type
Cwchar_t
¶Equivalent to the native
wchar_t
c-type (Int32)
Cfloat
¶Equivalent to the native
float
c-type (Float32)
Cdouble
¶Equivalent to the native
double
c-type (Float64)
LLVM Interface¶
llvmcall
(IR::String, ReturnType, (ArgumentType1, ...), ArgumentValue1, ...)¶Call LLVM IR string in the first argument. Similar to an LLVM function
define
block, arguments are available as consecutive unnamed SSA variables (%0, %1, etc.).Note that the argument type tuple must be a literal tuple, and not a tuple-valued variable or expression.
Each
ArgumentValue
tollvmcall
will be converted to the correspondingArgumentType
, by automatic insertion of calls tounsafe_convert(ArgumentType,cconvert(ArgumentType,ArgumentValue))
. (see also the documentation for each of these functions for further details). In most cases, this simply results in a call toconvert(ArgumentType,ArgumentValue)
.See
test/llvmcall.jl
for usage examples.