.\" Automatically generated by Pod::Man 4.14 (Pod::Simple 3.43)
.\"
.\" Standard preamble:
.\" ========================================================================
.de Sp \" Vertical space (when we can't use .PP)
.if t .sp .5v
.if n .sp
..
.de Vb \" Begin verbatim text
.ft CW
.nf
.ne \\$1
..
.de Ve \" End verbatim text
.ft R
.fi
..
.\" Set up some character translations and predefined strings.  \*(-- will
.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
.\" double quote, and \*(R" will give a right double quote.  \*(C+ will
.\" give a nicer C++.  Capital omega is used to do unbreakable dashes and
.\" therefore won't be available.  \*(C` and \*(C' expand to `' in nroff,
.\" nothing in troff, for use with C<>.
.tr \(*W-
.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
.ie n \{\
.    ds -- \(*W-
.    ds PI pi
.    if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
.    if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\"  diablo 12 pitch
.    ds L" ""
.    ds R" ""
.    ds C` ""
.    ds C' ""
'br\}
.el\{\
.    ds -- \|\(em\|
.    ds PI \(*p
.    ds L" ``
.    ds R" ''
.    ds C`
.    ds C'
'br\}
.\"
.\" Escape single quotes in literal strings from groff's Unicode transform.
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.\"
.\" If the F register is >0, we'll generate index entries on stderr for
.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
.\" entries marked with X<> in POD.  Of course, you'll have to process the
.\" output yourself in some meaningful fashion.
.\"
.\" Avoid warning from groff about undefined register 'F'.
.de IX
..
.nr rF 0
.if \n(.g .if rF .nr rF 1
.if (\n(rF:(\n(.g==0)) \{\
.    if \nF \{\
.        de IX
.        tm Index:\\$1\t\\n%\t"\\$2"
..
.        if !\nF==2 \{\
.            nr % 0
.            nr F 2
.        \}
.    \}
.\}
.rr rF
.\" ========================================================================
.\"
.IX Title "FFI::C 3pm"
.TH FFI::C 3pm "2023-02-06" "perl v5.36.0" "User Contributed Perl Documentation"
.\" For nroff, turn off justification.  Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.if n .ad l
.nh
.SH "NAME"
FFI::C \- C data types for FFI
.SH "VERSION"
.IX Header "VERSION"
version 0.15
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
In C:
.PP
.Vb 1
\& #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;
.Ve
.PP
In Perl:
.PP
.Vb 1
\& use FFI::C;
\& 
\& package ColorValue {
\&   FFI::C\->struct([
\&     red   => \*(Aquint8\*(Aq,
\&     green => \*(Aquint8\*(Aq,
\&     blue  => \*(Aquint8\*(Aq,
\&   ]);
\& }
\& 
\& package NamedColor {
\&   FFI::C\->struct([
\&     name  => \*(Aqstring(22)\*(Aq,
\&     value => \*(Aqcolor_value_t\*(Aq,
\&   ]);
\& }
\& 
\& package ArrayNamedColor {
\&   FFI::C\->array([\*(Aqnamed_color_t\*(Aq => 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]\en",
\&     $color\->name,
\&     $color\->value\->red,
\&     $color\->value\->green,
\&     $color\->value\->blue;
\& }
\& 
\& package AnyInt {
\&   FFI::C\->union([
\&     u8  => \*(Aquint8\*(Aq,
\&     u16 => \*(Aquint16\*(Aq,
\&     u32 => \*(Aquint32\*(Aq,
\&     u64 => \*(Aquint64\*(Aq,
\&   ]);
\& }
\& 
\& my $int = AnyInt\->new({ u8 => 42 });
\& print $int\->u32;
.Ve
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
This distribution provides tools for building classes to interface for common C
data types.  Arrays, \f(CW\*(C`struct\*(C'\fR, \f(CW\*(C`union\*(C'\fR and nested types based on those are
supported.
.PP
Core FFI::Platypus also provides FFI::Platypus::Record for manipulating and
passing structured data.  Typically you want to use \s-1FFI::C\s0 instead, the main
exception is when you need to pass structured data by value instead of by
reference.
.PP
To work with C APIs that work with C file pointers you can use
FFI::C::File and FFI::C::PosixFile.  For C APIs that expose the \s-1POSIX\s0
\&\f(CW\*(C`stat\*(C'\fR structure use FFI::C::Stat.
.SH "METHODS"
.IX Header "METHODS"
.SS "ffi"
.IX Subsection "ffi"
.Vb 2
\& FFI::C\->ffi($ffi);
\& my $ffi = FFI::C\->ffi;
.Ve
.PP
Get or set the FFI::Platypus instance used for the current Perl file
(\f(CW\*(C`.pl\*(C'\fR or \f(CW\*(C`.pm\*(C'\fR).
.PP
By default a new Platypus instance is created the on the first call to
\&\f(CW\*(C`ffi\*(C'\fR, or when a new type is created with \f(CW\*(C`struct\*(C'\fR, \f(CW\*(C`union\*(C'\fR or \f(CW\*(C`array\*(C'\fR
below, so if you want to use your own Platypus instance make sure that
you set it as soon as possible.
.PP
The Platypus instance is file scoped because scoping on just one package
doesn't make sense if you are defining multiple types in one file since
each type must be in its own package.  It also doesn't make sense to make
the Platypus instance global, because different distributions would
conflict.
.SS "struct"
.IX Subsection "struct"
.Vb 2
\& FFI::C\->struct($name, \e@members);
\& FFI::C\->struct(\e@members);
.Ve
.PP
Generate a new FFI::C::Struct class with the given \f(CW@members\fR into
the calling package.  (\f(CW@members\fR should be a list of name/type pairs).
You may optionally give a \f(CW$name\fR which will be used for the
FFI::Platypus type name for the generated class.  If you do not
specify a \f(CW$name\fR, a C style name will be generated from the last segment
in the calling package name by converting to snake case and appending a
\&\f(CW\*(C`_t\*(C'\fR to the end.
.PP
As an example, given:
.PP
.Vb 6
\& package MyLibrary::FooBar {
\&   FFI::C\->struct([
\&     a => \*(Aquint8\*(Aq,
\&     b => \*(Aqfloat\*(Aq,
\&   ]);
\& };
.Ve
.PP
You can use \f(CW\*(C`MyLibrary::FooBar\*(C'\fR via the file scoped FFI::Platypus instance
using the type \f(CW\*(C`foo_bar_t\*(C'\fR.
.PP
.Vb 2
\& my $foobar = MyLibrary::FooBar\->new({ a => 1, b => 3.14 });
\& $ffi\->function( my_library_func => [ \*(Aqfoo_bar_t\*(Aq ] => \*(Aqvoid\*(Aq )\->call($foobar);
.Ve
.SS "union"
.IX Subsection "union"
.Vb 2
\& FFI::C\->union($name, \e@members);
\& FFI::C\->union(\e@members);
.Ve
.PP
This works exactly like the \f(CW\*(C`struct\*(C'\fR method above, except a
FFI::C::Union class is generated instead.
.SS "array"
.IX Subsection "array"
.Vb 4
\& FFI::C\->array($name, [$type, $count]);
\& FFI::C\->array($name, [$type]);
\& FFI::C\->array([$type, $count]);
\& FFI::C\->array([$type]);
.Ve
.PP
This is similar to \f(CW\*(C`struct\*(C'\fR and \f(CW\*(C`union\*(C'\fR above, except FFI::C::Array is
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.
.SS "enum"
.IX Subsection "enum"
.Vb 4
\& FFI::C\->enum($name, \e@values, \e%config);
\& FFI::C\->enum(\e@values, \e%config);
\& FFI::C\->enum(\e@values, \e%config);
\& FFI::C\->enum(\e@values);
.Ve
.PP
Defines an enum.  The \f(CW@values\fR and \f(CW%config\fR are passed to
FFI::Platypus::Type::Enum, except the constants are exported
to the calling package by default.
.SH "EXAMPLES"
.IX Header "EXAMPLES"
.SS "unix time struct"
.IX Subsection "unix time struct"
.Vb 2
\& 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    => \*(Aqint\*(Aq,
\&     tm_min    => \*(Aqint\*(Aq,
\&     tm_hour   => \*(Aqint\*(Aq,
\&     tm_mday   => \*(Aqint\*(Aq,
\&     tm_mon    => \*(Aqint\*(Aq,
\&     tm_year   => \*(Aqint\*(Aq,
\&     tm_wday   => \*(Aqint\*(Aq,
\&     tm_yday   => \*(Aqint\*(Aq,
\&     tm_isdst  => \*(Aqint\*(Aq,
\&     tm_gmtoff => \*(Aqlong\*(Aq,
\&     _tm_zone  => \*(Aqopaque\*(Aq,
\&   ]);
\& 
\&   # For now \*(Aqstring\*(Aq 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(\*(Aqopaque\*(Aq, \*(Aqstring\*(Aq, $self\->_tm_zone);
\&   }
\& 
\&   # attach the C localtime function
\&   $ffi\->attach( localtime => [\*(Aqtime_t*\*(Aq] => \*(Aqtm\*(Aq, sub {
\&     my($inner, $class, $time) = @_;
\&     $time = time unless defined $time;
\&     $inner\->(\e$time);
\&   });
\& }
\& 
\& # now we can actually use our My::UnixTime class
\& my $time = Unix::TimeStruct\->localtime;
\& printf "time is %d:%d:%d %s\en",
\&   $time\->tm_hour,
\&   $time\->tm_min,
\&   $time\->tm_sec,
\&   $time\->tm_zone;
.Ve
.SH "CAVEATS"
.IX Header "CAVEATS"
\&\s-1FFI::C\s0 objects must be passed into C via FFI::Platypus by pointers.
So-called \*(L"pass-by-value\*(R" is not and will not be supported.  For
\&\*(L"pass-by-value\*(R" record types, you should instead use FFI::Platypus::Record.
.SH "SEE ALSO"
.IX Header "SEE ALSO"
.IP "\s-1FFI::C\s0" 4
.IX Item "FFI::C"
.PD 0
.IP "FFI::C::Array" 4
.IX Item "FFI::C::Array"
.IP "FFI::C::ArrayDef" 4
.IX Item "FFI::C::ArrayDef"
.IP "FFI::C::Def" 4
.IX Item "FFI::C::Def"
.IP "FFI::C::File" 4
.IX Item "FFI::C::File"
.IP "FFI::C::PosixFile" 4
.IX Item "FFI::C::PosixFile"
.IP "FFI::C::Struct" 4
.IX Item "FFI::C::Struct"
.IP "FFI::C::StructDef" 4
.IX Item "FFI::C::StructDef"
.IP "FFI::C::Union" 4
.IX Item "FFI::C::Union"
.IP "FFI::C::UnionDef" 4
.IX Item "FFI::C::UnionDef"
.IP "FFI::C::Util" 4
.IX Item "FFI::C::Util"
.IP "FFI::Platypus::Record" 4
.IX Item "FFI::Platypus::Record"
.PD
.SH "AUTHOR"
.IX Header "AUTHOR"
Graham Ollis <plicease@cpan.org>
.SH "COPYRIGHT AND LICENSE"
.IX Header "COPYRIGHT AND LICENSE"
This software is copyright (c) 2020\-2022 by Graham Ollis.
.PP
This is free software; you can redistribute it and/or modify it under
the same terms as the Perl 5 programming language system itself.