C Interface

ccallKeyword

ccall((symbol, library) or function_pointer, ReturnType, (ArgumentType1, ...), ArgumentValue1, ...)

Call function in C-exported shared library, specified by (function name, 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 by dlsym.

Each ArgumentValue to the ccall will be converted to the corresponding ArgumentType, by automatic insertion of calls to unsafe_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 to convert(ArgumentType, ArgumentValue).

source

Core.Intrinsics.cglobalFunction

cglobal((symbol, library) [, type=Void])

Obtain a pointer to a global variable in a C-exported shared library, specified exactly as in ccall. Returns a Ptr{Type}, defaulting to Ptr{Void} if no Type argument is supplied. The values can be read or written by unsafe_load or unsafe_store!, respectively.

source

Base.cfunctionFunction

cfunction(function::Function, ReturnType::Type, ArgumentTypes::Type)

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.

Examples

julia> function foo(x::Int, y::Int)
           return x + y
       end

julia> cfunction(foo, Int, Tuple{Int,Int})
Ptr{Void} @0x000000001b82fcd0
source

Base.unsafe_convertFunction

unsafe_convert(T,x)

Convert x to a value of type T

In cases where convert would need to take a Julia object and turn it into a Ptr, 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 argument x to this function should never be an expression, only a variable name or field reference. For example, x=a.b.c is acceptable, but x=[a,b,c] is not.

The unsafe prefix on this function indicates that using the result of this function after the x argument to this function is no longer accessible to the program may cause undefined behavior, including program corruption or segfaults, at any later time.

source

Base.cconvertFunction

cconvert(T,x)

Convert x to a value of type T, typically by calling convert(T,x)

In cases where x cannot be safely converted to T, unlike convert, cconvert may return an object of a type different from T, which however is suitable for unsafe_convert to handle.

Neither convert nor cconvert should take a Julia object and turn it into a Ptr.

source

Base.unsafe_loadFunction

unsafe_load(p::Ptr{T}, i::Integer=1)

Load a value of type T from the address of the ith element (1-indexed) starting at p. This is equivalent to the C expression p[i-1].

The unsafe prefix on this function indicates that no validation is performed on the pointer p to ensure that it is valid. Incorrect usage may segfault your program or return garbage answers, in the same manner as C.

source

Base.unsafe_store!Function

unsafe_store!(p::Ptr{T}, x, i::Integer=1)

Store a value of type T to the address of the ith element (1-indexed) starting at p. This is equivalent to the C expression p[i-1] = x.

The unsafe prefix on this function indicates that no validation is performed on the pointer p to ensure that it is valid. Incorrect usage may corrupt or segfault your program, in the same manner as C.

source

Base.unsafe_copy!Method

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 pointers dest and src to ensure that they are valid. Incorrect usage may corrupt or segfault your program, in the same manner as C.

source

Base.unsafe_copy!Method

unsafe_copy!(dest::Array, do, src::Array, so, N)

Copy N elements from a source array to a destination, starting at offset so in the source and do 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.

source

Base.copy!Method

copy!(dest, src) -> dest

Copy all elements from collection src to array dest.

source

Base.copy!Method

copy!(dest, do, src, so, N)

Copy N elements from collection src starting at offset so, to array dest starting at offset do. Returns dest.

source

Base.pointerFunction

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" like unsafe_convert.

Calling Ref(array[, index]) is generally preferable to this function.

source

Base.unsafe_wrapMethod

unsafe_wrap(Array, pointer::Ptr{T}, dims, own=false)

Wrap a Julia Array object around the data at the address given by pointer, without making a copy. The pointer element type T determines the array element type. dims is either an integer (for a 1d array) or a tuple of the array dimensions. own optionally specifies whether Julia should take ownership of the memory, calling free on the pointer when the array is no longer referenced.

This function is labelled "unsafe" because it will crash if pointer is not a valid memory address to data of the requested length.

source

Base.pointer_from_objrefFunction

pointer_from_objref(x)

Get the memory address of a Julia object as a Ptr. The existence of the resulting Ptr will not protect the object from garbage collection, so you must ensure that the object remains referenced for the whole time that the Ptr will be used.

source

Base.unsafe_pointer_to_objrefFunction

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.

source

Base.disable_sigintFunction

disable_sigint(f::Function)

Disable Ctrl-C handler during execution of a function on the current task, for calling external code that may call julia code that is not interrupt safe. Intended to be called using do block syntax as follows:

disable_sigint() do
    # interrupt-unsafe code
    ...
end

This is not needed on worker threads (Threads.threadid() != 1) since the InterruptException will only be delivered to the master thread. External functions that do not call julia code or julia runtime automatically disable sigint during their execution.

source

Base.reenable_sigintFunction

reenable_sigint(f::Function)

Re-enable Ctrl-C handler during execution of a function. Temporarily reverses the effect of disable_sigint.

source

Base.systemerrorFunction

systemerror(sysfunc, iftrue)

Raises a SystemError for errno with the descriptive string sysfunc if iftrue is true

source

Core.PtrType

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.

source

Core.RefType

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 the Ref itself is referenced.

When passed as a ccall argument (either as a Ptr or Ref type), a Ref object will be converted to a native pointer to the data it references.

There is no invalid (NULL) Ref.

source

Base.CcharType

Cchar

Equivalent to the native char c-type.

source

Base.CucharType

Cuchar

Equivalent to the native unsigned char c-type (UInt8).

source

Base.CshortType

Cshort

Equivalent to the native signed short c-type (Int16).

source

Base.CushortType

Cushort

Equivalent to the native unsigned short c-type (UInt16).

source

Base.CintType

Cint

Equivalent to the native signed int c-type (Int32).

source

Base.CuintType

Cuint

Equivalent to the native unsigned int c-type (UInt32).

source

Base.ClongType

Clong

Equivalent to the native signed long c-type.

source

Base.CulongType

Culong

Equivalent to the native unsigned long c-type.

source

Base.ClonglongType

Clonglong

Equivalent to the native signed long long c-type (Int64).

source

Base.CulonglongType

Culonglong

Equivalent to the native unsigned long long c-type (UInt64).

source

Base.Cintmax_tType

Cintmax_t

Equivalent to the native intmax_t c-type (Int64).

source

Base.Cuintmax_tType

Cuintmax_t

Equivalent to the native uintmax_t c-type (UInt64).

source

Base.Csize_tType

Csize_t

Equivalent to the native size_t c-type (UInt).

source

Base.Cssize_tType

Cssize_t

Equivalent to the native ssize_t c-type.

source

Base.Cptrdiff_tType

Cptrdiff_t

Equivalent to the native ptrdiff_t c-type (Int).

source

Base.Cwchar_tType

Cwchar_t

Equivalent to the native wchar_t c-type (Int32).

source

Base.CfloatType

Cfloat

Equivalent to the native float c-type (Float32).

source

Base.CdoubleType

Cdouble

Equivalent to the native double c-type (Float64).

source

LLVM Interface

Core.Intrinsics.llvmcallFunction

llvmcall(IR::String, ReturnType, (ArgumentType1, ...), ArgumentValue1, ...)
llvmcall((declarations::String, 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.).

The optional declarations string contains external functions declarations that are necessary for llvm to compile the IR string. Multiple declarations can be passed in by separating them with line breaks.

Note that the argument type tuple must be a literal tuple, and not a tuple-valued variable or expression.

Each ArgumentValue to llvmcall will be converted to the corresponding ArgumentType, by automatic insertion of calls to unsafe_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 to convert(ArgumentType, ArgumentValue).

See test/llvmcall.jl for usage examples.

source

© 2009–2016 Jeff Bezanson, Stefan Karpinski, Viral B. Shah, and other contributors
Licensed under the MIT License.
https://docs.julialang.org/en/release-0.6/stdlib/c/