ForeignFunctionLoad

ForeignFunctionLoad[lib,fun,{argtype1,argtype2,…}rettype]

loads the function fun with the specified argument and output types from the library lib.

ForeignFunctionLoad[ptr,{argtype1,argtype2,…}rettype]

creates a foreign function from the function pointer ptr.

Details

  • ForeignFunctionLoad returns the ForeignFunction object.
  • lib is resolved with FindLibrary.
  • lib must be a C-compatible dynamic library.
  • Supported types generally align with those supported by the Wolfram Compiler.
  • Possible argument and return types and their corresponding C types include:
  • "UnsignedInteger8"uint8_tunsigned 8-bit integer
    "Integer8"int8_tsigned 8-bit integer
    "UnsignedInteger16"uint16_tunsigned 16-bit integer
    "Integer16"int16_tsigned 16-bit integer
    "UnsignedInteger32"uint32_tunsigned 32-bit integer
    "Integer32"int32_tsigned 32-bit integer
    "UnsignedInteger64"uint64_tunsigned 64-bit integer
    "Integer64"int64_tsigned 64-bit integer
    "CUnsignedChar"unsigned charC-compatible unsigned char
    "CSignedChar"signed charC-compatible signed char
    "CUnsignedShort"unsigned shortC-compatible unsigned short
    "CShort"shortC-compatible short
    "CUnsignedInt"unsigned intC-compatible unsigned int
    "CInt"intC-compatible int
    "CUnsignedLong"unsigned longC-compatible unsigned long
    "CLong"longC-compatible long
    "CSizeT"size_tC-compatible size_t
    "CFloat"floatC-compatible float
    "CDouble"doubleC-compatible double
    "OpaqueRawPointer"void*opaque pointer
    "RawPointer"::[t]t*typed pointer
    {ty1,ty2,…}struct {ty1 f1; ty2 f2; …}struct or product type
    "Void"voidno output (only in output types)
  • Struct or product types can also be written as "ListTuple"::[ty1,ty2, …].
  • In ForeignFunctionLoad[ptr,…], ptr must be an OpaqueRawPointer pointing to a valid function in a library.

Examples

open allclose all

Basic Examples  (1)

Load a function from a library:

Call the function:

Scope  (2)

ForeignFunctionLoad uses FindLibrary to locate libraries:

Alternatively, find the library once with FindLibrary and pass it to ForeignFunctionLoad:

Get the pointer to a function in a library:

Load the foreign function by using the function pointer and specifying its type:

Applications  (2)

Create a foreign function for the RAND_bytes function from OpenSSL:

Create a buffer into which the random bytes can be written:

Generate the random bytes by calling RAND_bytes:

Read the output:

Package into a function:

The foreign function is very efficient:

Implement SHA256 using OpenSSL:

Create a buffer containing the plaintext to hash:

Create a buffer into which to write the hash:

Execute the hash:

Read the results from the ciphertext buffer:

Compare with the built-in function Hash:

Package into a function:

The packaged function is very efficient:

Properties & Relations  (1)

ForeignFunctionLoad can generally create callable links to libraries faster than custom links can be compiled:

However, the custom compiled versions can have less overhead:

Possible Issues  (3)

If the library does not exist, a Failure is returned:

If the function does not exist, a Failure is returned:

ForeignFunctionLoad will return $Failed if a type is not supported:

Wolfram Research (2023), ForeignFunctionLoad, Wolfram Language function, https://reference.wolfram.com/language/ref/ForeignFunctionLoad.html.

Text

Wolfram Research (2023), ForeignFunctionLoad, Wolfram Language function, https://reference.wolfram.com/language/ref/ForeignFunctionLoad.html.

CMS

Wolfram Language. 2023. "ForeignFunctionLoad." Wolfram Language & System Documentation Center. Wolfram Research. https://reference.wolfram.com/language/ref/ForeignFunctionLoad.html.

APA

Wolfram Language. (2023). ForeignFunctionLoad. Wolfram Language & System Documentation Center. Retrieved from https://reference.wolfram.com/language/ref/ForeignFunctionLoad.html

BibTeX

@misc{reference.wolfram_2024_foreignfunctionload, author="Wolfram Research", title="{ForeignFunctionLoad}", year="2023", howpublished="\url{https://reference.wolfram.com/language/ref/ForeignFunctionLoad.html}", note=[Accessed: 21-November-2024 ]}

BibLaTeX

@online{reference.wolfram_2024_foreignfunctionload, organization={Wolfram Research}, title={ForeignFunctionLoad}, year={2023}, url={https://reference.wolfram.com/language/ref/ForeignFunctionLoad.html}, note=[Accessed: 21-November-2024 ]}