Fiddle::Pointer is a class to handle C pointers

Class Methods

Get the underlying pointer for ruby object val and return it as a Fiddle::Pointer object.

Examples

# Automatically freeing the pointer when the block is exited - recommended
Fiddle::Pointer.malloc(size, Fiddle::RUBY_FREE) do |pointer|
  ...
end

# Manually freeing but relying on the garbage collector otherwise
pointer = Fiddle::Pointer.malloc(size, Fiddle::RUBY_FREE)
...
pointer.call_free

# Relying on the garbage collector - may lead to unlimited memory allocated before freeing any, but safe
pointer = Fiddle::Pointer.malloc(size, Fiddle::RUBY_FREE)
...

# Only manually freeing
pointer = Fiddle::Pointer.malloc(size)
begin
  ...
ensure
  Fiddle.free pointer
end

# No free function and no call to free - the native memory will leak if the pointer is garbage collected
pointer = Fiddle::Pointer.malloc(size)
...

Allocate size bytes of memory and associate it with an optional freefunc.

If a block is supplied, the pointer will be yielded to the block instead of being returned, and the return value of the block will be returned. A freefunc must be supplied if a block is.

If a freefunc is supplied it will be called once, when the pointer is garbage collected or when the block is left if a block is supplied or when the user calls call_free, whichever happens first. freefunc must be an address pointing to a function or an instance of Fiddle::Function.

Create a new pointer to address with an optional size and freefunc.

freefunc will be called when the instance is garbage collected.

Or read the memory at address address with length len and return a string with that memory

Get the underlying pointer for ruby object val and return it as a Fiddle::Pointer object.

Write bytes in str to the location pointed to by address.

Instance Methods

Returns a new pointer instance that has been advanced n bytes.

An alias for ptr

Returns a new pointer instance that has been moved back n bytes.

An alias for ref

Returns -1 if less than, 0 if equal to, 1 if greater than other.

Returns nil if ptr cannot be compared to other.

Returns true if other wraps the same pointer, otherwise returns false.

Returns integer stored at index.

If start and length are given, a string containing the bytes from start of length will be returned.

Set the value at index to int.

Or, set the memory at start until length with the contents of string, the memory from dl_cptr, or the memory pointed at by the memory address addr.

Call the free function for this pointer. Calling more than once will do nothing. Does nothing if there is no free function attached.

An alias for ==

Get the free function for this pointer.

Returns a new instance of Fiddle::Function.

See Fiddle::Function.new

Set the free function for this pointer to function in the given Fiddle::Function.

Returns if the free function for this pointer has been called.

Returns a string formatted with an easily readable representation of the internal state of the pointer.

Returns true if this is a null pointer.

Returns a new Fiddle::Pointer instance that is a dereferenced pointer for this pointer.

Analogous to the star operator in C.

Returns a new Fiddle::Pointer instance that is a reference pointer for this pointer.

Analogous to the ampersand operator in C.

Get the size of this pointer.

Set the size of this pointer to size

Returns the integer memory location of this pointer.

An alias for to_i
ptr.to_s        => string
ptr.to_s(len)   => string

Returns the pointer contents as a string.

When called with no arguments, this method will return the contents until the first NULL byte.

When called with len, a string of len bytes will be returned.

See to_str

ptr.to_str        => string
ptr.to_str(len)   => string

Returns the pointer contents as a string.

When called with no arguments, this method will return the contents with the length of this pointer’s size.

When called with len, a string of len bytes will be returned.

See to_s

Cast this pointer to a ruby object.