FFI::C(3pm)

💖 FFI::C 💖 — like, C data types but for FFI, bestie

okay so real talk: this is FFI::C, a Perl module (that's the (3pm) bit, iykyk) and it's literally the moment C data types stopped being scary. come sit with me. 🫶

---

✨ VERSION ✨

version 0.15 — yes queen, we're on 0.15 💅

---

🌸 SYNOPSIS 🌸

so first, the C side of things, no cap:

#include <stdint.h>

typedef struct {
  uint8_t red;
  uint8_t green;
  uint8_t blue;
} color_value_t;

typedef struct {
  char name[22];
  color_value_t value;
} named_color_t;

typedef named_color_t array_named_color_t[4];

typedef union {
  uint8_t  u8;
  uint16_t u16;
  uint32_t u32;
  uint64_t u64;
} anyint_t;

and now the Perl side, where it gets cute:

use FFI::C;

package ColorValue {
  FFI::C->struct([
    red   => 'uint8',
    green => 'uint8',
    blue  => 'uint8',
  ]);
}

package NamedColor {
  FFI::C->struct([
    name  => 'string(22)',
    value => 'color_value_t',
  ]);
}

package ArrayNamedColor {
  FFI::C->array(['named_color_t' => 4]);
};

my $array = ArrayNamedColor->new([
  { name => "red",    value => { red   => 255 } },
  { name => "green",  value => { green => 255 } },
  { name => "blue",   value => { blue  => 255 } },
  { name => "purple", value => { red   => 255,
                                 blue  => 255 } },
]);

# dim each color by 1/2
foreach my $color (@$array)
{
  $color->value->red  ( $color->value->red   / 2 );
  $color->value->green( $color->value->green / 2 );
  $color->value->blue ( $color->value->blue  / 2 );
}

# print out the colors
foreach my $color (@$array)
{
  printf "%s [%02x %02x %02x]\n",
    $color->name,
    $color->value->red,
    $color->value->green,
    $color->value->blue;
}

package AnyInt {
  FFI::C->union([
    u8  => 'uint8',
    u16 => 'uint16',
    u32 => 'uint32',
    u64 => 'uint64',
  ]);
}

my $int = AnyInt->new({ u8 => 42 });
print $int->u32;

look at that. she's gorgeous. 😭✨

---

🦋 DESCRIPTION 🦋

so this whole distribution is basically a little toolkit for building classes that interface with common C data types. arrays, struct, union, and nested types built on top of those? all supported, all slaying. 👑

now, plot twist: core FFI::Platypus also ships FFI::Platypus::Record for manipulating and passing structured data around. but bestie, typically you want to use FFI::C instead. the one main exception? that's when you need to pass structured data by value instead of by reference. that's the whole vibe check. 🎀

also, if you're working with C APIs that work with C file pointers, you can use FFI::C::File and FFI::C::PosixFile. and for C APIs that expose the POSIX stat structure, use FFI::C::Stat. so many besties, all of them iconic. 🧚

---

💅 METHODS 💅

🌈 ffi

FFI::C->ffi($ffi);
my $ffi = FFI::C->ffi;

get or set the FFI::Platypus instance used for the current Perl file (that's your .pl or .pm, fr fr).

by default a new Platypus instance is created on the first call to ffi, or when a new type is created with struct, union or array below — so if you wanna use your own Platypus instance, make sure you set it as soon as possible. like, immediately. don't dawdle. ⏰

and here's why the Platypus instance is file scoped: scoping on just one package doesn't make sense if you're defining multiple types in one file, because each type has to live in its own package. and making the Platypus instance global? also doesn't make sense, because different distributions would conflict with each other. it's giving "we thought about this, bestie." 😌

🍓 struct

FFI::C->struct($name, \@members);
FFI::C->struct(\@members);

generates a new FFI::C::Struct class with the given @members into the calling package. (@members should be a list of name/type pairs, obvs.) you may optionally give a $name, which gets used for the FFI::Platypus type name for the generated class. if you don't specify a $name, a C style name gets generated from the last segment in the calling package name — by converting to snake case and appending a "_t" to the end. so thoughtful. ✨

as an example, given:

package MyLibrary::FooBar {
  FFI::C->struct([
    a => 'uint8',
    b => 'float',
  ]);
};

you can use MyLibrary::FooBar via the file scoped FFI::Platypus instance using the type foo_bar_t. see how that worked? 🎀

my $foobar = MyLibrary::FooBar->new({ a => 1, b => 3.14 });
$ffi->function( my_library_func => [ 'foo_bar_t' ] => 'void' )->call($foobar);

💜 union

FFI::C->union($name, \@members);
FFI::C->union(\@members);

this works exactly like the struct method above, except a FFI::C::Union class is generated instead. same energy, different class. 💅

🌸 array

FFI::C->array($name, [$type, $count]);
FFI::C->array($name, [$type]);
FFI::C->array([$type, $count]);
FFI::C->array([$type]);

similar to struct and union above, except FFI::C::Array is what gets generated. for an array you give it the member type and the element count. the element count is optional for variable length arrays — but keep in mind that when you create such an array you do need to provide a size. no skipping that part, bestie. 🫶

⭐ enum

FFI::C->enum($name, \@values, \%config);
FFI::C->enum(\@values, \%config);
FFI::C->enum(\@values, \%config);
FFI::C->enum(\@values);

defines an enum. the @values and %config get passed to FFI::Platypus::Type::Enum — except the constants are exported to the calling package by default. surprise! a little gift. 🎁

---

🔥 EXAMPLES 🔥

🌙 unix time struct

use FFI::Platypus 1.00;
use FFI::C;

my $ffi = FFI::Platypus->new(
  api => 1,
  lib => [undef],
);
FFI::C->ffi($ffi);

package Unix::TimeStruct {

  FFI::C->struct(tm => [
    tm_sec    => 'int',
    tm_min    => 'int',
    tm_hour   => 'int',
    tm_mday   => 'int',
    tm_mon    => 'int',
    tm_year   => 'int',
    tm_wday   => 'int',
    tm_yday   => 'int',
    tm_isdst  => 'int',
    tm_gmtoff => 'long',
    _tm_zone  => 'opaque',
  ]);

  # For now 'string' is unsupported by FFI::C, but we
  # can cast the time zone from an opaque pointer to
  # string.
  sub tm_zone {
    my $self = shift;
    $ffi->cast('opaque', 'string', $self->_tm_zone);
  }

  # attach the C localtime function
  $ffi->attach( localtime => ['time_t*'] => 'tm', sub {
    my($inner, $class, $time) = @_;
    $time = time unless defined $time;
    $inner->(\$time);
  });
}

# now we can actually use our My::UnixTime class
my $time = Unix::TimeStruct->localtime;
printf "time is %d:%d:%d %s\n",
  $time->tm_hour,
  $time->tm_min,
  $time->tm_sec,
  $time->tm_zone;

main character energy, honestly. look at her go. 👑💖

---

💀 CAVEATS 💀

FFI::C objects must be passed into C via FFI::Platypus by pointers. so-called "pass-by-value" is not and will not be supported. periodt. 🚫

for "pass-by-value" record types, you should instead use FFI::Platypus::Record. that's the move, bestie.

---

🎀 SEE ALSO 🎀

• FFI::C
• FFI::C::Array
• FFI::C::ArrayDef
• FFI::C::Def
• FFI::C::File
• FFI::C::PosixFile
• FFI::C::Struct
• FFI::C::StructDef
• FFI::C::Union
• FFI::C::UnionDef
• FFI::C::Util
• FFI::Platypus::Record

the whole friend group. obsessed. 🫶

---

🌈 AUTHOR 🌈

Graham Ollis <plicease@cpan.org>

---

💖 COPYRIGHT AND LICENSE 💖

This software is copyright (c) 2020-2022 by Graham Ollis.

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

---

and that's the whole page, bestie!! 🎉 this was perl v5.36.0, dated 2023-02-06, and it's the FFI::C(3pm) manual page. go forth and struct. 💅✨🦋