.\" -*- mode: troff; coding: utf-8 -*-
.\" Automatically generated by Pod::Man 5.01 (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
..
.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>.
.ie n \{\
.    ds C` ""
.    ds C' ""
'br\}
.el\{\
.    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::Platypus::Buffer 3pm"
.TH FFI::Platypus::Buffer 3pm 2024-01-10 "perl v5.38.2" "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::Platypus::Buffer \- Convert scalars to C buffers
.SH VERSION
.IX Header "VERSION"
version 2.08
.SH SYNOPSIS
.IX Header "SYNOPSIS"
.Vb 3
\& use FFI::Platypus::Buffer;
\& my($pointer, $size) = scalar_to_buffer $scalar;
\& my $scalar2 = buffer_to_scalar $pointer, $size;
.Ve
.SH DESCRIPTION
.IX Header "DESCRIPTION"
A common pattern in C is to pass a "buffer" or region of memory into a
function with a pair of arguments, an opaque pointer and the size of the
memory region.  In Perl the equivalent structure is a scalar containing
a string of bytes.  This module provides portable functions for
converting a Perl string or scalar into a buffer and back.
.PP
These functions are implemented using pack and unpack and
so they should be relatively fast.
.PP
Both functions are exported by default, but you can explicitly export
one or neither if you so choose.
.PP
A better way to do this might be with custom types see
FFI::Platypus::API and FFI::Platypus::Type.  These functions were
taken from the now obsolete FFI::Util module, as they may be useful
in some cases.
.PP
\&\fBCaution\fR: This module provides great power in the way that you
interact with C code, but with that power comes great responsibility.
Since you are dealing with blocks of memory you need to take care to
understand the underlying ownership model of these pointers.
.SH FUNCTIONS
.IX Header "FUNCTIONS"
.SS scalar_to_buffer
.IX Subsection "scalar_to_buffer"
.Vb 1
\& my($pointer, $size) = scalar_to_buffer $scalar;
.Ve
.PP
Convert a string scalar into a buffer.  Returned in order are a pointer
to the start of the string scalar's memory region and the size of the
region.
.PP
You should NEVER try to free \f(CW$pointer\fR.
.PP
When you pass this pointer and size into a C function, it has direct
access to the data stored in your scalar, so it is important that you
not resize or free the scalar while it is in use by the C code.  Typically
if you are passing a buffer into a C function which reads or writes to
the buffer, but does not keep the pointer for later use you are okay.
If the buffer is in use long term by the C code, then you should consider
copying the buffer instead.  For example:
.PP
.Vb 2
\& use FFI::Platypus::Buffer qw( scalar_to_buffer );
\& use FFI::Platypus::Memory qw( malloc memcpy free )
\& 
\& my($ptr, $size) = scalar_to_buffer $string;
\& c_function_that_does_not_keep_ptr( $ptr, $size); # okay
\& 
\& my($ptr, $size) = scalar_to_buffer $string;
\& my $ptr_copy = malloc($size);
\& memcpy($ptr_copy, $ptr, $size);
\& c_function_that_DOES_keep_ptr( $ptr_copy, $size); # also okay
\& 
\& ...
\& 
\& # later when you know that the c code is no longer using the pointer
\& # Since you allocated the copy, you are responsible for free\*(Aqing it.
\& free($ptr_copy);
.Ve
.SS scalar_to_pointer
.IX Subsection "scalar_to_pointer"
.Vb 1
\& my $pointer = scalar_to_pointer $scalar;
.Ve
.PP
Get the pointer to the scalar.  (Similar to \f(CW\*(C`scalar_to_buffer\*(C'\fR above, but
the size of the scalar is not computed or returned).
.PP
Not exported by default, but may be exported on request.
.SS buffer_to_scalar
.IX Subsection "buffer_to_scalar"
.Vb 1
\& my $scalar = buffer_to_scalar $pointer, $size;
.Ve
.PP
Convert the buffer region defined by the pointer and size into a string
scalar.
.PP
Because of the way memory management works in Perl, the buffer is copied
from the buffer into the scalar.  If this pointer was returned from C
land, then you should only free it if you allocated it.
.SS grow
.IX Subsection "grow"
.Vb 1
\& grow $scalar, $size, \e%options;
.Ve
.PP
Ensure that the scalar can contain at least \f(CW$size\fR bytes.  The
following are recognized:
.IP "clear => \fIboolean\fR" 4
.IX Item "clear => boolean"
If true, \f(CW$scalar\fR is cleared prior to being enlarged.  This
avoids copying the existing contents to the reallocated memory
if they are not needed.
.Sp
.Vb 1
\&  For example, after
\& 
\&   $scalar = "my string";
\&   grow $scalar, 100, { clear => 0 };
.Ve
.Sp
\&\f(CW\*(C`$scalar == "my string"\*(C'\fR, while after
.Sp
.Vb 2
\&   $scalar = "my string";
\&   grow $scalar, 100;
.Ve
.Sp
\&\f(CW\*(C`length($scalar) == 0\*(C'\fR
.Sp
It defaults to \f(CW\*(C`true\*(C'\fR.
.IP "set_length => \fIboolean\fR" 4
.IX Item "set_length => boolean"
If true, the length of the \fIstring\fR in the \f(CW$scalar\fR is set to \f(CW$size\fR.
(See the discussion in "set_used_length".)  This is useful if a
foreign function writes exactly \f(CW$size\fR bytes to \f(CW$scalar\fR, as it avoids
a subsequent call to \f(CW\*(C`set_used_length\*(C'\fR.  Contrast this
.Sp
.Vb 3
\&  grow my $scalar, 100;
\&  read_exactly_100_bytes_into_scalar( scalar_to_pointer($scalar) );
\&  @chars = unpack( \*(Aqc*\*(Aq, $scalar );
.Ve
.Sp
with this:
.Sp
.Vb 4
\&  grow my $scalar, 100, { set_length => 0 };
\&  read_exactly_100_bytes_into_scalar( scalar_to_pointer($scalar) );
\&  set_used_length( $scalar, 100 );
\&  @chars = unpack( \*(Aqc*\*(Aq, $scalar );
.Ve
.Sp
It defaults to \f(CW\*(C`true\*(C'\fR.
.PP
Any pointers obtained with \f(CW\*(C`scalar_to_pointer\*(C'\fR or \f(CW\*(C`scalar_to_buffer\*(C'\fR
are no longer valid after growing the scalar.
.PP
Not exported by default, but may be exported on request.
.SS set_used_length
.IX Subsection "set_used_length"
.Vb 1
\& set_used_length $scalar, $length;
.Ve
.PP
Update Perl's notion of the length of the string in the scalar. A
string scalar keeps track of two lengths: the number of available
bytes and the number of used bytes.  When a string scalar is
used as a buffer by a foreign function, it is necessary to indicate
to Perl how many bytes were actually written to it so that Perl's
string functions (such as \f(CW\*(C`substr\*(C'\fR or \f(CW\*(C`unpack\*(C'\fR) will work correctly.
.PP
If \f(CW$length\fR is larger than what the scalar can hold, it is set to the
maximum possible size.
.PP
In the following example, the foreign routine \f(CW\*(C`read_doubles\*(C'\fR
may fill the buffer with up to a set number of doubles, returning the
number actually written.
.PP
.Vb 3
\&  my $sizeof_double = $ffi\->sizeof( \*(Aqdouble\*(Aq );
\&  my $max_doubles = 100;
\&  my $max_length = $max_doubles * $sizeof_double;
\& 
\&  my $buffer;                   # length($buffer) == 0
\&  grow $buffer, $max_length;    # length($buffer) is still  0
\&  my $pointer = scalar_to_pointer($buffer);
\& 
\&  my $num_read = read_doubles( $pointer, $max_doubles );
\&                                # length($buffer) is still == 0
\& 
\&  set_used_length $buffer, $num_read * $sizeof_double;
\&                                # length($buffer) is finally != 0
\& 
\&  # unpack the native doubles into a Perl array
\&  my @doubles = unpack( \*(Aqd*\*(Aq, $buffer );  # @doubles == $num_read
.Ve
.PP
Not exported by default, but may be exported on request.
.SS window
.IX Subsection "window"
.Vb 3
\& window $scalar, $pointer;
\& window $scalar, $pointer, $size;
\& window $scalar, $pointer, $size, $utf8;
.Ve
.PP
This makes the scalar a read-only window into the arbitrary region of
memory defined by \f(CW$pointer\fR, pointing to the start of the region
and \f(CW$size\fR, the size of the region.  If \f(CW$size\fR is omitted then
it will assume a C style string and use the C \f(CW\*(C`strlen\*(C'\fR function to
determine the size (the terminating \f(CW\*(Aq\e0\*(Aq\fR will not be included).
.PP
This can be useful if you have a C function that returns a buffer
pair (pointer, size), and want to access it from Perl without having
to copy the data.  This can also be useful when interfacing with
programming languages that store strings as a address/length pair
instead of a pointer to null-terminated sequence of bytes.
.PP
You can specify \f(CW$utf8\fR to set the UTF\-8 flag on the scalar.  Note
that the behavior of setting the UTF\-8 flag on a buffer that does
not contain UTF\-8 as understood by the version of Perl that you are
running is undefined.
.PP
\&\fIHint\fR: If you have a buffer that needs to be free'd by C once the
scalar falls out of scope you can use Variable::Magic to apply
magic to the scalar and free the pointer once it falls out of scope.
.PP
.Vb 3
\& use FFI::Platypus::Buffer qw( scalar_to_pointer );
\& use FFI::Platypus::Memory qw( strdup free );
\& use Variable::Magic qw( wizard cast );
\& 
\& my $free_when_out_of_scope = wizard(
\&   free => sub {
\&     my $ptr = scalar_to_pointer ${$_[0]};
\&     free $ptr;
\&   }
\& );
\& 
\& my $ptr = strdup "Hello Perl";
\& my $scalar;
\& window $scalar, $ptr, 10;
\& cast $scalar, $free_when_out_of_scope;
\& undef $ptr;  # don\*(Aqt need to track the pointer anymore.
\& 
\& # we can now use scalar as a regular read\-only Perl variable
\& print $scalar, "\en";  # prints "Hello Perl" without the \e0
\& 
\& # this will free the C pointer
\& undef $scalar;
.Ve
.PP
\&\fIHint\fR: Returning a scalar string from a Perl function actually
copies the value.  If you want to return a string without copying
then you need to return a reference.
.PP
.Vb 8
\& sub c_string
\& {
\&   my $ptr = strdup "Hello Perl";
\&   my $scalar;
\&   window $scalar, $ptr, 10;
\&   cast $scalar, $free_when_out_of_scope;
\&   \e$scalar;
\& }
\& 
\& my $ref = c_string();
\& print $$ref, "\en";  # prints "Hello Perl" without the \e0
.Ve
.PP
Not exported by default, but may be exported on request.
.SH "SEE ALSO"
.IX Header "SEE ALSO"
.IP FFI::Platypus 4
.IX Item "FFI::Platypus"
Main Platypus documentation.
.SH AUTHOR
.IX Header "AUTHOR"
Author: Graham Ollis <plicease@cpan.org>
.PP
Contributors:
.PP
Bakkiaraj Murugesan (bakkiaraj)
.PP
Dylan Cali (calid)
.PP
pipcet
.PP
Zaki Mughal (zmughal)
.PP
Fitz Elliott (felliott)
.PP
Vickenty Fesunov (vyf)
.PP
Gregor Herrmann (gregoa)
.PP
Shlomi Fish (shlomif)
.PP
Damyan Ivanov
.PP
Ilya Pavlov (Ilya33)
.PP
Petr Písař (ppisar)
.PP
Mohammad S Anwar (MANWAR)
.PP
Håkon Hægland (hakonhagland, HAKONH)
.PP
Meredith (merrilymeredith, MHOWARD)
.PP
Diab Jerius (DJERIUS)
.PP
Eric Brine (IKEGAMI)
.PP
szTheory
.PP
José Joaquín Atria (JJATRIA)
.PP
Pete Houston (openstrike, HOUSTON)
.SH "COPYRIGHT AND LICENSE"
.IX Header "COPYRIGHT AND LICENSE"
This software is copyright (c) 2015\-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.