<!-- GENERATED by docs/sphinx/bin/20-reference (p5) from FFI/Platypus/mod.rs. Do not edit. -->

```{index} single: FFI::Platypus
```

# FFI::Platypus

```{pperl-module-badges} FFI::Platypus
```

Call C functions in shared libraries from Perl, with no compiler.

`FFI::Platypus->new(api => 2, lib => ...)` finds a library;
`$ffi->attach(name => [argument types] => return type)` makes a C
function a Perl sub, `$ffi->function(...)` an object to call. Types
cover the C integers and floats, `long double` and the complex types,
strings, pointers and fixed arrays of them, records (C structs) by
pointer and by value, closures (Perl subs C can call back), objects
and custom types written in Perl.

This is a native implementation of FFI::Platypus 2.12's compiled part,
`Platypus.xs` with its `xs/*.xs` and helpers; its Perl modules are
used unchanged. Its calls, types, records and closures are those of
pperl's own [Peta::FFI](../Peta/FFI), which can express everything
FFI::Platypus can.


## Synopsis

```perl
use FFI::Platypus 2.00;

my $ffi = FFI::Platypus->new( api => 2, lib => undef );
$ffi->attach( puts   => ['string'] => 'int' );
$ffi->attach( strlen => ['string'] => 'size_t' );

puts("hello");
my $n = strlen("hello");                # 5

my $qsort = $ffi->function( qsort =>
    ['int*', 'size_t', 'size_t', '(opaque,opaque)->int'] => 'void' );
```

## Differences from upstream

- Reading an array member of a record does not leak the array; perl
  leaks it and the reference on every read.
- An index past an `opaque[N]` member warns "illegal index" and
  returns nothing, as for the other array members; perl reads beyond
  the member.
- A reference to a hash or code for a pointer argument under api 2
  warns and passes NULL; perl crashes.
- An argument with get-magic - a regex capture, a tied scalar - passes
  its value; perl passes 0 for a number and NULL for a string, which
  crashes `strlen($1)`.
- A closure that a library calls from a thread of its own stops the
  program with a message saying so; perl runs Perl on that thread and
  crashes ("longjmp causes uninitialized stack frame").

## Modules

- [`FFI::Platypus::API`](Platypus/API.md) - Platypus arguments and return value API for custom types
- [`FFI::Platypus::Buffer`](Platypus/Buffer.md) - Convert scalars to C buffers
- [`FFI::Platypus::Bundle`](Platypus/Bundle.md) - Bundle foreign code with your Perl module
- [`FFI::Platypus::Closure`](Platypus/Closure.md) - Platypus closure object
- [`FFI::Platypus::Constant`](Platypus/Constant.md) - Define constants in C space for Perl
- [`FFI::Platypus::DL`](Platypus/DL.md) - Slightly non-portable interface to libdl
- [`FFI::Platypus::Function`](Platypus/Function.md) - An FFI function object
- [`FFI::Platypus::Internal`](Platypus/Internal.md) - For internal use only
- [`FFI::Platypus::Lang`](Platypus/Lang.md) - Language specific customizations
- [`FFI::Platypus::Legacy`](Platypus/Legacy.md) - Legacy Platypus interfaces
- [`FFI::Platypus::Memory`](Platypus/Memory.md) - Memory functions for FFI
- [`FFI::Platypus::Record`](Platypus/Record.md) - FFI support for structured records data
- [`FFI::Platypus::ShareConfig`](Platypus/ShareConfig.md) - FFI::Platypus::ShareConfig
- [`FFI::Platypus::Type`](Platypus/Type.md) - Defining types for FFI::Platypus
- [`FFI::Platypus::TypeParser`](Platypus/TypeParser.md) - FFI Type Parser

```{toctree}
:hidden:
:maxdepth: 1

Platypus/API
Platypus/Buffer
Platypus/Bundle
Platypus/Closure
Platypus/Constant
Platypus/DL
Platypus/Function
Platypus/Internal
Platypus/Lang
Platypus/Legacy
Platypus/Memory
Platypus/Record
Platypus/ShareConfig
Platypus/Type
Platypus/TypeParser
```