Module FFI::Library
In: lib/ffi/library.rb

This module is the base to use native functions.

A basic usage may be:

 require 'ffi'

 module Hello
   extend FFI::Library
   ffi_lib FFI::Library::LIBC
   attach_function 'puts', [ :string ], :int
 end

 Hello.puts("Hello, World")

Methods

Constants

CURRENT_PROCESS = FFI::CURRENT_PROCESS
LIBC = FFI::Platform::LIBC
FlagsMap = { :global => DynamicLibrary::RTLD_GLOBAL, :local => DynamicLibrary::RTLD_LOCAL, :lazy => DynamicLibrary::RTLD_LAZY, :now => DynamicLibrary::RTLD_NOW   Flags used in {ffi_lib}.

This map allows you to supply symbols to {ffi_lib_flags} instead of the actual constants.

Public Class methods

@param mod extended object @return [nil] @raise {RuntimeError} if mod is not a Module Test if extended object is a Module. If not, raise RuntimeError.

Public Instance methods

@overload attach_function(func, args, returns, options = {})

 @example attach function without an explicit name
   module Foo
     extend FFI::Library
     ffi_lib FFI::Library::LIBC
     attach_function :malloc, [:size_t], :pointer
   end
   # now callable via Foo.malloc

@overload attach_function(name, func, args, returns, options = {})

 @example attach function with an explicit name
   module Bar
     extend FFI::Library
     ffi_lib FFI::Library::LIBC
     attach_function :c_malloc, :malloc, [:size_t], :pointer
   end
   # now callable via Bar.c_malloc

Attach C function func to this module.

@param [to_s] name name of ruby method to attach as @param [to_s] func name of C function to attach @param [Array<Symbol>] args an array of types @param [Symbol] returns type of return value @option options [Boolean] :blocking (@blocking) set to true if the C function is a blocking call @option options [Symbol] :convention (:default) calling convention (see {ffi_convention}) @option options [FFI::Enums] :enums @option options [Hash] :type_map

@return [FFI::VariadicInvoker]

@raise [FFI::NotFoundError] if func cannot be found in the attached libraries (see {ffi_lib})

@overload attach_variable(mname, cname, type)

 @example
  module Bar
    extend FFI::Library
    ffi_lib 'my_lib'
    attach_variable :c_myvar, :myvar, :long
  end
  # now callable via Bar.c_myvar

@overload attach_variable(cname, type)

 @example
  module Bar
    extend FFI::Library
    ffi_lib 'my_lib'
    attach_variable :myvar, :long
  end
  # now callable via Bar.myvar

@param [to_s] mname name of ruby method to attach as @param [to_s] cname name of C variable to attach @param [DataConverter, Struct, Symbol, Type] type C varaible‘s type @return [DynamicLibrary::Symbol] @raise {FFI::NotFoundError} if cname cannot be found in libraries

Attach C variable cname to this module.

@overload callback(name, params, ret) @overload callback(params, ret) @param name callback name to add to type map @param [Array] params array of parameters’ types @param [DataConverter, Struct, Symbol, Type] ret callback return type @return [FFI::CallbackInfo]

@overload enum(name, values)

 Create a named enum.
 @example
  enum :foo, [:zero, :one, :two]  # named enum
 @param [Symbol] name name for new enum
 @param [Array] values values for enum

@overload enum(*args)

 Create an unnamed enum.
 @example
  enum :zero, :one, :two  # unnamed enum
 @param args values for enum

@overload enum(values)

 Create an unnamed enum.
 @example
  enum [:zero, :one, :two]  # unnamed enum, equivalent to above example
 @param [Array] values values for enum

@return [FFI::Enum] Create a new {FFI::Enum}.

@param name @return [FFI::Enum] Find an enum by name.

@param symbol @return [FFI::Enum] Find an enum by a symbol it contains.

Set the calling convention for {attach_function} and {callback}

@see en.wikipedia.org/wiki/Stdcall#stdcall @note +:stdcall+ is typically used for attaching Windows API functions

@param [Symbol] convention one of +:default+, +:stdcall+ @return [Symbol] the new calling convention

@param [Array] names names of libraries to load @return [Array<DynamicLibrary>] @raise {LoadError} if a library cannot be opened Load native libraries.

Sets library flags for {ffi_lib}.

@example

  ffi_lib_flags(:lazy, :local) # => 5

@param [Symbol, …] flags (see {FlagsMap}) @return [Fixnum] the new value

@see ffi_lib @return [Array<FFI::DynamicLibrary>] array of currently loaded FFI libraries @raise [LoadError] if no libraries have been loaded (using {ffi_lib}) Get FFI libraries loaded using {ffi_lib}.

@param [DataConverter, Type, Struct, Symbol] t type to find @return [Type] Find a type definition.

@param [to_s] name function name @param [Array] arg_types function‘s argument types @return [Array<String>] This function returns a list of possible names to lookup. @note Function names on windows may be decorated if they are using stdcall. See

  * http://en.wikipedia.org/wiki/Name_mangling#C_name_decoration_in_Microsoft_Windows
  * http://msdn.microsoft.com/en-us/library/zxk0tw93%28v=VS.100%29.aspx
  * http://en.wikibooks.org/wiki/X86_Disassembly/Calling_Conventions#STDCALL
  Note that decorated names can be overridden via def files.  Also note that the
  windows api, although using, doesn't have decorated names.

@param [DataConverter, Symbol, Type] old @param add @param [] info @return [FFI::Enum, FFI::Type] Register or get an already registered type definition.

To register a new type definition, old should be a {FFI::Type}. add is in this case the type definition.

If old is a {DataConverter}, a {Type::Mapped} is returned.

If old is +:enum+

  • and add is an Array, a call to {enum} is made with add as single parameter;
  • in others cases, info is used to create a named enum.

If old is a key for type map, typedef get old type definition.

[Validate]