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)

  @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 variable's 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)

  @param [#to_s] mname name of ruby method to attach as
  @param [DataConverter, Struct, Symbol, Type] type C variable's type
  @example
    module Bar
      extend FFI::Library
      ffi_lib 'my_lib'
      attach_variable :myvar, :long
    end
    # now callable via Bar.myvar

@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)

  @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

@overload callback(params, ret)

  @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

@overload enum(native_type, name, values)

 Create a named enum and specify the native type.
 @example
  enum FFI::Type::UINT64, :foo, [:zero, :one, :two]  # named enum
 @param [FFI::Type] native_type native type for new enum
 @param [Symbol] name name for new enum
 @param [Array] values values for enum

@overload enum(native_type, *args)

 Create an unnamed enum and specify the native type.
 @example
  enum FFI::Type::UINT64, :zero, :one, :two  # unnamed enum
 @param [FFI::Type] native_type native type for new enum
 @param args values for enum

@overload enum(native_type, values)

 Create an unnamed enum and specify the native type.
 @example
  enum Type::UINT64, [:zero, :one, :two]  # unnamed enum, equivalent to above example
 @param [FFI::Type] native_type native type for new enum
 @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.

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.

@param [DataConverter, Symbol, Type] old @param [Symbol] add @param [Symbol] info @return [FFI::Enum, FFI::Type]

[Validate]