C Interface¶
-
ccall
((symbol, library) or fptr, RetType, (ArgType1, ...), ArgVar1, ...)¶ Call function in C-exported shared library, specified by
(function name, library)
tuple, where each component is a String or :Symbol. Alternatively, ccall may be used to call a function pointer returned by dlsym, but note that this usage is generally discouraged to facilitate future static compilation. Note that the argument type tuple must be a literal tuple, and not a tuple-valued variable or expression.
-
cglobal
((symbol, library) or ptr[, 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
(fun::Function, RetType::Type, (ArgTypes...))¶ 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() # body retval::Float64 end bar = cfunction(foo, Float64, ())
-
dlopen
(libfile::String[, flags::Integer])¶ Load a shared library, returning an opaque handle.
The optional flags argument is a bitwise-or of zero or more of
RTLD_LOCAL
,RTLD_GLOBAL
,RTLD_LAZY
,RTLD_NOW
,RTLD_NODELETE
,RTLD_NOLOAD
,RTLD_DEEPBIND
, andRTLD_FIRST
. These are converted to the corresponding flags of the POSIX (and/or GNU libc and/or MacOS) dlopen command, if possible, or are ignored if the specified functionality is not available on the current platform. The default isRTLD_LAZY|RTLD_DEEPBIND|RTLD_LOCAL
. An important usage of these flags, on POSIX platforms, is to specifyRTLD_LAZY|RTLD_DEEPBIND|RTLD_GLOBAL
in order for the library’s symbols to be available for usage in other shared libraries, in situations where there are dependencies between shared libraries.
-
dlopen_e
(libfile::String[, flags::Integer])¶ Similar to
dlopen()
, except returns aNULL
pointer instead of raising errors.
-
dlsym
(handle, sym)¶ Look up a symbol from a shared library handle, return callable function pointer on success.
-
dlsym_e
(handle, sym)¶ Look up a symbol from a shared library handle, silently return NULL pointer on lookup failure.
-
dlclose
(handle)¶ Close shared library referenced by handle.
-
find_library
(names, locations)¶ Searches for the first library in
names
in the paths in thelocations
list,DL_LOAD_PATH
, or system library paths (in that order) which can successfully be dlopen’d. On success, the return value will be one of the names (potentially prefixed by one of the paths in locations). This string can be assigned to aglobal const
and used as the library name in futureccall
‘s. On failure, it returns the empty string.
-
DL_LOAD_PATH
¶ When calling
dlopen
, the paths in this list will be searched first, in order, before searching the system locations for a valid library handle.
-
c_malloc
(size::Integer) → Ptr{Void}¶ Call
malloc
from the C standard library.
-
c_calloc
(num::Integer, size::Integer) → Ptr{Void}¶ Call
calloc
from the C standard library.
-
c_realloc
(addr::Ptr, size::Integer) → Ptr{Void}¶ Call
realloc
from the C standard library.
-
c_free
(addr::Ptr)¶ Call
free
from the C standard library.
-
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]
.
-
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
.
-
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.
-
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).
-
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
(a[, 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.
-
pointer
(type, int) Convert an integer to a pointer of the specified element type.
-
pointer_to_array
(p, dims[, own])¶ 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
(obj)¶ 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
.
-
errno
([code])¶ Get the value of the C library’s
errno
. If an argument is specified, it is used to set the value oferrno
.The value of
errno
is only valid immediately after accall
to a C library routine that sets it. Specifically, you cannot callerrno
at the next prompt in a REPL, because lots of code is executed between prompts.
-
systemerror
(sysfunc, iftrue)¶ Raises a
SystemError
forerrno
with the descriptive stringsysfunc
ifbool
is true
-
strerror
(n)¶ Convert a system call error code to a descriptive string
-
Cchar
¶ Equivalent to the native
char
c-type
-
Cuchar
¶ Equivalent to the native
unsigned char
c-type (Uint8)
-
Cshort
¶ Equivalent to the native
signed short
c-type (Int16)
-
Cushort
¶ Equivalent to the native
unsigned short
c-type (Uint16)
-
Cint
¶ Equivalent to the native
signed int
c-type (Int32)
-
Cuint
¶ Equivalent to the native
unsigned int
c-type (Uint32)
-
Clong
¶ Equivalent to the native
signed long
c-type
-
Culong
¶ Equivalent to the native
unsigned long
c-type
-
Clonglong
¶ Equivalent to the native
signed long long
c-type (Int64)
-
Culonglong
¶ Equivalent to the native
unsigned long long
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)