1FFI::Platypus::Buffer(3U)ser Contributed Perl DocumentatiFoFnI::Platypus::Buffer(3)
2
3
4

NAME

6       FFI::Platypus::Buffer - Convert scalars to C buffers
7

VERSION

9       version 1.10
10

SYNOPSIS

12        use FFI::Platypus::Buffer;
13        my($pointer, $size) = scalar_to_buffer $scalar;
14        my $scalar2 = buffer_to_scalar $pointer, $size;
15

DESCRIPTION

17       A common pattern in C is to pass a "buffer" or region of memory into a
18       function with a pair of arguments, an opaque pointer and the size of
19       the memory region.  In Perl the equivalent structure is a scalar
20       containing a string of bytes.  This module provides portable functions
21       for converting a Perl string or scalar into a buffer and back.
22
23       These functions are implemented using pack and unpack and so they
24       should be relatively fast.
25
26       Both functions are exported by default, but you can explicitly export
27       one or neither if you so choose.
28
29       A better way to do this might be with custom types see
30       FFI::Platypus::API and FFI::Platypus::Type.  These functions were taken
31       from the now obsolete FFI::Util module, as they may be useful in some
32       cases.
33
34       Caution: This module provides great power in the way that you interact
35       with C code, but with that power comes great responsibility.  Since you
36       are dealing with blocks of memory you need to take care to understand
37       the underlying ownership model of these pointers.
38

FUNCTIONS

40   scalar_to_buffer
41        my($pointer, $size) = scalar_to_buffer $scalar;
42
43       Convert a string scalar into a buffer.  Returned in order are a pointer
44       to the start of the string scalar's memory region and the size of the
45       region.
46
47       You should NEVER try to free $pointer.
48
49       When you pass this pointer and size into a C function, it has direct
50       access to the data stored in your scalar, so it is important that you
51       not resize or free the scalar while it is in use by the C code.
52       Typically if you are passing a buffer into a C function which reads or
53       writes to the buffer, but does not keep the pointer for later use you
54       are okay.  If the buffer is in use long term by the C code, then you
55       should consider copying the buffer instead.  For example:
56
57        use FFI::Platypus::Buffer qw( scalar_to_buffer );
58        use FFI::Platypus::Memory qw( malloc memcpy free )
59
60        my($ptr, $size) = scalar_to_buffer $string;
61        c_function_thaat_does_not_keep_ptr( $ptr, $size); # okay
62
63        my($ptr, $size) = scalar_to_buffer $string;
64        my $ptr_copy = malloc($size);
65        memcpy($ptr_copy, $ptr, $size);
66        c_function_that_DOES_keep_ptr( $ptr_copy, $size); # also okay
67
68        ...
69
70        # later when you know that the c code is no longer using the pointer
71        # Since you allocated the copy, you are responsible for free'ing it.
72        free($ptr_copy);
73
74   scalar_to_pointer
75        my $pointer = scalar_to_pointer $scalar;
76
77       Get the pointer to the scalar.  (Similar to "scalar_to_buffer" above,
78       but the size of the scalar is not computed or returned).
79
80       Not exported by default, but may be exported on request.
81
82   buffer_to_scalar
83        my $scalar = buffer_to_scalar $pointer, $size;
84
85       Convert the buffer region defined by the pointer and size into a string
86       scalar.
87
88       Because of the way memory management works in Perl, the buffer is
89       copied from the buffer into the scalar.  If this pointer was returned
90       from C land, then you should only free it if you allocated it.
91

SEE ALSO

93       FFI::Platypus
94           Main Platypus documentation.
95

AUTHOR

97       Author: Graham Ollis <plicease@cpan.org>
98
99       Contributors:
100
101       Bakkiaraj Murugesan (bakkiaraj)
102
103       Dylan Cali (calid)
104
105       pipcet
106
107       Zaki Mughal (zmughal)
108
109       Fitz Elliott (felliott)
110
111       Vickenty Fesunov (vyf)
112
113       Gregor Herrmann (gregoa)
114
115       Shlomi Fish (shlomif)
116
117       Damyan Ivanov
118
119       Ilya Pavlov (Ilya33)
120
121       Petr Pisar (ppisar)
122
123       Mohammad S Anwar (MANWAR)
124
125       Håkon Hægland (hakonhagland, HAKONH)
126
127       Meredith (merrilymeredith, MHOWARD)
128
129       Diab Jerius (DJERIUS)
130

132       This software is copyright (c) 2015,2016,2017,2018,2019 by Graham
133       Ollis.
134
135       This is free software; you can redistribute it and/or modify it under
136       the same terms as the Perl 5 programming language system itself.
137
138
139
140perl v5.30.1                      2020-02-06          FFI::Platypus::Buffer(3)
Impressum