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

attach_function attach_variable callback enum enum_type enum_value extended ffi_convention ffi_lib ffi_lib_flags ffi_libraries find_type function_names typedef

### 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

extended(mod)

@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

attach_function(name, func, args, returns = nil, options = nil)

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

attach_variable(mname, a1, a2 = nil)

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

callback(*args)

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

enum(*args)

@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}.

enum_type(name)

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

enum_value(symbol)

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

ffi_convention(convention = nil)

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

ffi_lib(*names)

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

ffi_lib_flags(*flags)

Sets library flags for {ffi_lib}.

@example

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

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

ffi_libraries()

@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}.

find_type(t)

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

function_names(name, arg_types)

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

typedef(old, add, info=nil)

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