1package FFI::Platypus::Buffer; 2 3use strict; 4use warnings; 5use 5.008004; 6use FFI::Platypus; 7use Exporter qw( import ); 8 9our @EXPORT = qw( scalar_to_buffer buffer_to_scalar ); 10our @EXPORT_OK = qw ( scalar_to_pointer grow set_used_length window ); 11 12# ABSTRACT: Convert scalars to C buffers 13our $VERSION = '1.56'; # VERSION 14 15 16use constant _incantation => 17 $^O eq 'MSWin32' && do { require Config; $Config::Config{archname} =~ /MSWin32-x64/ } 18 ? 'Q' 19 : 'L!'; 20 21 22sub scalar_to_buffer ($) 23{ 24 (unpack(_incantation, pack 'P', $_[0]), do { use bytes; length $_[0] }); 25} 26 27 28sub scalar_to_pointer ($) 29{ 30 unpack(_incantation, pack 'P', $_[0]); 31} 32 33 34sub buffer_to_scalar ($$) 35{ 36 unpack 'P'.$_[1], pack _incantation, defined $_[0] ? $_[0] : 0; 37} 38 391; 40 41__END__ 42 43=pod 44 45=encoding UTF-8 46 47=head1 NAME 48 49FFI::Platypus::Buffer - Convert scalars to C buffers 50 51=head1 VERSION 52 53version 1.56 54 55=head1 SYNOPSIS 56 57 use FFI::Platypus::Buffer; 58 my($pointer, $size) = scalar_to_buffer $scalar; 59 my $scalar2 = buffer_to_scalar $pointer, $size; 60 61=head1 DESCRIPTION 62 63A common pattern in C is to pass a "buffer" or region of memory into a 64function with a pair of arguments, an opaque pointer and the size of the 65memory region. In Perl the equivalent structure is a scalar containing 66a string of bytes. This module provides portable functions for 67converting a Perl string or scalar into a buffer and back. 68 69These functions are implemented using L<pack and unpack|perlpacktut> and 70so they should be relatively fast. 71 72Both functions are exported by default, but you can explicitly export 73one or neither if you so choose. 74 75A better way to do this might be with custom types see 76L<FFI::Platypus::API> and L<FFI::Platypus::Type>. These functions were 77taken from the now obsolete L<FFI::Util> module, as they may be useful 78in some cases. 79 80B<Caution>: This module provides great power in the way that you 81interact with C code, but with that power comes great responsibility. 82Since you are dealing with blocks of memory you need to take care to 83understand the underlying ownership model of these pointers. 84 85=head1 FUNCTIONS 86 87=head2 scalar_to_buffer 88 89 my($pointer, $size) = scalar_to_buffer $scalar; 90 91Convert a string scalar into a buffer. Returned in order are a pointer 92to the start of the string scalar's memory region and the size of the 93region. 94 95You should NEVER try to free C<$pointer>. 96 97When you pass this pointer and size into a C function, it has direct 98access to the data stored in your scalar, so it is important that you 99not resize or free the scalar while it is in use by the C code. Typically 100if you are passing a buffer into a C function which reads or writes to 101the buffer, but does not keep the pointer for later use you are okay. 102If the buffer is in use long term by the C code, then you should consider 103copying the buffer instead. For example: 104 105 use FFI::Platypus::Buffer qw( scalar_to_buffer ); 106 use FFI::Platypus::Memory qw( malloc memcpy free ) 107 108 my($ptr, $size) = scalar_to_buffer $string; 109 c_function_that_does_not_keep_ptr( $ptr, $size); # okay 110 111 my($ptr, $size) = scalar_to_buffer $string; 112 my $ptr_copy = malloc($size); 113 memcpy($ptr_copy, $ptr, $size); 114 c_function_that_DOES_keep_ptr( $ptr_copy, $size); # also okay 115 116 ... 117 118 # later when you know that the c code is no longer using the pointer 119 # Since you allocated the copy, you are responsible for free'ing it. 120 free($ptr_copy); 121 122=head2 scalar_to_pointer 123 124 my $pointer = scalar_to_pointer $scalar; 125 126Get the pointer to the scalar. (Similar to C<scalar_to_buffer> above, but 127the size of the scalar is not computed or returned). 128 129Not exported by default, but may be exported on request. 130 131=head2 buffer_to_scalar 132 133 my $scalar = buffer_to_scalar $pointer, $size; 134 135Convert the buffer region defined by the pointer and size into a string 136scalar. 137 138Because of the way memory management works in Perl, the buffer is copied 139from the buffer into the scalar. If this pointer was returned from C 140land, then you should only free it if you allocated it. 141 142=head2 grow 143 144 grow $scalar, $size, \%options; 145 146Ensure that the scalar can contain at least C<$size> bytes. The 147following are recognized: 148 149=over 150 151=item clear => I<boolean> 152 153If true, C<$scalar> is cleared prior to being enlarged. This 154avoids copying the existing contents to the reallocated memory 155if they are not needed. 156 157 For example, after 158 159 $scalar = "my string"; 160 grow $scalar, 100, { clear => 0 }; 161 162C<$scalar == "my string">, while after 163 164 $scalar = "my string"; 165 grow $scalar, 100; 166 167C<length($scalar) == 0> 168 169It defaults to C<true>. 170 171=item set_length => I<boolean> 172 173If true, the length of the I<string> in the C<$scalar> is set to C<$size>. 174(See the discussion in L</set_used_length>.) This is useful if a 175foreign function writes exactly C<$size> bytes to C<$scalar>, as it avoids 176a subsequent call to C<set_used_length>. Contrast this 177 178 grow my $scalar, 100; 179 read_exactly_100_bytes_into_scalar( scalar_to_pointer($scalar) ); 180 @chars = unpack( 'c*', $scalar ); 181 182with this: 183 184 grow my $scalar, 100, { set_length => 0 }; 185 read_exactly_100_bytes_into_scalar( scalar_to_pointer($scalar) ); 186 set_used_length( $scalar, 100 ); 187 @chars = unpack( 'c*', $scalar ); 188 189It defaults to C<true>. 190 191=back 192 193Any pointers obtained with C<scalar_to_pointer> or C<scalar_to_buffer> 194are no longer valid after growing the scalar. 195 196Not exported by default, but may be exported on request. 197 198=head2 set_used_length 199 200 set_used_length $scalar, $length; 201 202Update Perl's notion of the length of the string in the scalar. A 203string scalar keeps track of two lengths: the number of available 204bytes and the number of used bytes. When a string scalar is 205used as a buffer by a foreign function, it is necessary to indicate 206to Perl how many bytes were actually written to it so that Perl's 207string functions (such as C<substr> or C<unpack>) will work correctly. 208 209If C<$length> is larger than what the scalar can hold, it is set to the 210maximum possible size. 211 212In the following example, the foreign routine C<read_doubles> 213may fill the buffer with up to a set number of doubles, returning the 214number actually written. 215 216 my $sizeof_double = $ffi->sizeof( 'double' ); 217 my $max_doubles = 100; 218 my $max_length = $max_doubles * $sizeof_double; 219 220 my $buffer; # length($buffer) == 0 221 grow $buffer, $max_length; # length($buffer) is still 0 222 my $pointer = scalar_to_pointer($buffer); 223 224 my $num_read = read_doubles( $pointer, $max_doubles ); 225 # length($buffer) is still == 0 226 227 set_used_length $buffer, $num_read * $sizeof_double; 228 # length($buffer) is finally != 0 229 230 # unpack the native doubles into a Perl array 231 my @doubles = unpack( 'd*', $buffer ); # @doubles == $num_read 232 233Not exported by default, but may be exported on request. 234 235=head2 window 236 237 window $scalar, $pointer; 238 window $scalar, $pointer, $size; 239 window $scalar, $pointer, $size, $utf8; 240 241This makes the scalar a read-only window into the arbitrary region of 242memory defined by C<$pointer>, pointing to the start of the region 243and C<$size>, the size of the region. If C<$size> is omitted then 244it will assume a C style string and use the C C<strlen> function to 245determine the size (the terminating C<'\0'> will not be included). 246 247This can be useful if you have a C function that returns a buffer 248pair (pointer, size), and want to access it from Perl without having 249to copy the data. This can also be useful when interfacing with 250programming languages that store strings as a address/length pair 251instead of a pointer to null-terminated sequence of bytes. 252 253You can specify C<$utf8> to set the UTF-8 flag on the scalar. Note 254that the behavior of setting the UTF-8 flag on a buffer that does 255not contain UTF-8 as understood by the version of Perl that you are 256running is undefined. 257 258I<Hint>: If you have a buffer that needs to be free'd by C once the 259scalar falls out of scope you can use L<Variable::Magic> to apply 260magic to the scalar and free the pointer once it falls out of scope. 261 262 use FFI::Platypus::Buffer qw( scalar_to_pointer ); 263 use FFI::Platypus::Memory qw( strdup free ); 264 use Variable::Magic qw( wizard cast ); 265 266 my $free_when_out_of_scope = wizard( 267 free => sub { 268 my $ptr = scalar_to_pointer ${$_[0]}; 269 free $ptr; 270 } 271 ); 272 273 my $ptr = strdup "Hello Perl"; 274 my $scalar; 275 window $scalar, $ptr, 10; 276 cast $scalar, $free_when_out_of_scope; 277 undef $ptr; # don't need to track the pointer anymore. 278 279 # we can now use scalar as a regular read-only Perl variable 280 print $scalar, "\n"; # prints "Hello Perl" without the \0 281 282 # this will free the C pointer 283 undef $scalar; 284 285I<Hint>: Returning a scalar string from a Perl function actually 286copies the value. If you want to return a string without copying 287then you need to return a reference. 288 289 sub c_string 290 { 291 my $ptr = strdup "Hello Perl"; 292 my $scalar; 293 window $scalar, $ptr, 10; 294 cast $scalar, $free_when_out_of_scope; 295 \$scalar; 296 } 297 298 my $ref = c_string(); 299 print $$ref, "\n"; # prints "Hello Perl" without the \0 300 301Not exported by default, but may be exported on request. 302 303=head1 SEE ALSO 304 305=over 4 306 307=item L<FFI::Platypus> 308 309Main Platypus documentation. 310 311=back 312 313=head1 AUTHOR 314 315Author: Graham Ollis E<lt>plicease@cpan.orgE<gt> 316 317Contributors: 318 319Bakkiaraj Murugesan (bakkiaraj) 320 321Dylan Cali (calid) 322 323pipcet 324 325Zaki Mughal (zmughal) 326 327Fitz Elliott (felliott) 328 329Vickenty Fesunov (vyf) 330 331Gregor Herrmann (gregoa) 332 333Shlomi Fish (shlomif) 334 335Damyan Ivanov 336 337Ilya Pavlov (Ilya33) 338 339Petr Písař (ppisar) 340 341Mohammad S Anwar (MANWAR) 342 343Håkon Hægland (hakonhagland, HAKONH) 344 345Meredith (merrilymeredith, MHOWARD) 346 347Diab Jerius (DJERIUS) 348 349Eric Brine (IKEGAMI) 350 351szTheory 352 353José Joaquín Atria (JJATRIA) 354 355Pete Houston (openstrike, HOUSTON) 356 357=head1 COPYRIGHT AND LICENSE 358 359This software is copyright (c) 2015,2016,2017,2018,2019,2020 by Graham Ollis. 360 361This is free software; you can redistribute it and/or modify it under 362the same terms as the Perl 5 programming language system itself. 363 364=cut 365