FFI::Platypus::Memory(3pm)

Usage

 use FFI::Platypus::Memory;
 
 # allocate 64 bytes of memory using the
 # libc malloc function.
 my $pointer = malloc 64;
 
 # use that memory wisely
 ...
 
 # free the memory when you are done.
 free $pointer;

Version

version 2.10

Overview

This module provides an interface to common memory functions provided by the standard C library. They may be useful when constructing interfaces to C libraries with FFI. It works mostly with the "opaque" type and it is worth reviewing the section on opaque pointers in FFI::Platypus::Type.

Allocating memory and forgetting to free it is a common source of memory leaks in C and when using this module. Very recent Perls have a "defer" keyword that lets you automatically call functions like "free" when a block ends. This can be especially handy when you have multiple code paths or possible exceptions to keep track of.

 use feature 'defer';
 use FFI::Platypus::Memory qw( malloc free );
 sub run {
   my $ptr = malloc 66;
   defer { free $ptr };
   my $data = do_something($ptr);
   # do not need to remember to place free $ptr here, as it will
   # run through defer.
   return $data;
 }

If you are not lucky enough to have the "defer" feature in your version of Perl you may be able to use Feature::Compat::Defer, which will use the feature if available, and provides its own mostly compatible version if not.

Functions

calloc

 my $pointer = calloc $count, $size;

The "calloc" function contiguously allocates enough space for $count objects that are $size bytes of memory each.

free

 free $pointer;

The "free" function frees the memory allocated by "malloc", "calloc", "realloc" or "strdup". It is important to only free memory that you yourself have allocated. A good way to crash your program is to try and free a pointer that some C library has returned to you.

malloc

 my $pointer = malloc $size;

The "malloc" function allocates $size bytes of memory.

memcpy

 memcpy $dst_pointer, $src_pointer, $size;

The "memcpy" function copies $size bytes from $src_pointer to $dst_pointer. It also returns $dst_pointer.

memset

 memset $buffer, $value, $length;

The "memset" function writes $length bytes of $value to the address specified by $buffer.

realloc

 my $new_pointer = realloc $old_pointer, $size;

The "realloc" function reallocates enough memory to fit $size bytes. It copies the existing data and frees $old_pointer.

If you pass "undef" in as $old_pointer, then it behaves exactly like "malloc":

 my $pointer = realloc undef, 64; # same as malloc 64

strcpy

 strcpy $opaque, $string;

Copies the string to the memory location pointed to by $opaque.

strdup

 my $pointer = strdup $string;

The "strdup" function allocates enough memory to contain $string and then copies it to that newly allocated memory. This version of "strdup" returns an opaque pointer type, not a string type. This may seem a little strange, but returning a string type would not be very useful in Perl.

strndup

 my $pointer = strndup $string, $max;

The same as "strdup" above, except at most $max characters will be copied in the new string.

Copyright and license

This is free software; you can redistribute it and/or modify it under the same terms as the Perl 5 programming language system itself.

Releases

5 releases since Debian 9 (Stretch); the text changed 4 times.

9
10
11
12
13