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

NAME

6       FFI::Platypus::Memory - Memory functions for FFI
7

VERSION

9       version 2.08
10

SYNOPSIS

12        use FFI::Platypus::Memory;
13
14        # allocate 64 bytes of memory using the
15        # libc malloc function.
16        my $pointer = malloc 64;
17
18        # use that memory wisely
19        ...
20
21        # free the memory when you are done.
22        free $pointer;
23

DESCRIPTION

25       This module provides an interface to common memory functions provided
26       by the standard C library.  They may be useful when constructing
27       interfaces to C libraries with FFI.  It works mostly with the "opaque"
28       type and it is worth reviewing the section on opaque pointers in
29       FFI::Platypus::Type.
30
31       Allocating memory and forgetting to free it is a common source of
32       memory leaks in C and when using this module.  Very recent Perls have a
33       "defer" keyword that lets you automatically call functions like "free"
34       when a block ends.  This can be especially handy when you have multiple
35       code paths or possible exceptions to keep track of.
36
37        use feature 'defer';
38        use FFI::Platypus::Memory qw( malloc free );
39
40        sub run {
41          my $ptr = malloc 66;
42          defer { free $ptr };
43
44          my $data = do_something($ptr);
45
46          # do not need to remember to place free $ptr here, as it will
47          # run through defer.
48
49          return $data;
50        }
51
52       If you are not lucky enough to have the "defer" feature in your version
53       of Perl you may be able to use Feature::Compat::Defer, which will use
54       the feature if available, and provides its own mostly compatible
55       version if not.
56

FUNCTIONS

58   calloc
59        my $pointer = calloc $count, $size;
60
61       The "calloc" function contiguously allocates enough space for $count
62       objects that are $size bytes of memory each.
63
64   free
65        free $pointer;
66
67       The "free" function frees the memory allocated by "malloc", "calloc",
68       "realloc" or "strdup".  It is important to only free memory that you
69       yourself have allocated.  A good way to crash your program is to try
70       and free a pointer that some C library has returned to you.
71
72   malloc
73        my $pointer = malloc $size;
74
75       The "malloc" function allocates $size bytes of memory.
76
77   memcpy
78        memcpy $dst_pointer, $src_pointer, $size;
79
80       The "memcpy" function copies $size bytes from $src_pointer to
81       $dst_pointer.  It also returns $dst_pointer.
82
83   memset
84        memset $buffer, $value, $length;
85
86       The "memset" function writes $length bytes of $value to the address
87       specified by $buffer.
88
89   realloc
90        my $new_pointer = realloc $old_pointer, $size;
91
92       The "realloc" function reallocates enough memory to fit $size bytes.
93       It copies the existing data and frees $old_pointer.
94
95       If you pass "undef" in as $old_pointer, then it behaves exactly like
96       "malloc":
97
98        my $pointer = realloc undef, 64; # same as malloc 64
99
100   strcpy
101        strcpy $opaque, $string;
102
103       Copies the string to the memory location pointed to by $opaque.
104
105   strdup
106        my $pointer = strdup $string;
107
108       The "strdup" function allocates enough memory to contain $string and
109       then copies it to that newly allocated memory.  This version of
110       "strdup" returns an opaque pointer type, not a string type.  This may
111       seem a little strange, but returning a string type would not be very
112       useful in Perl.
113
114   strndup
115        my $pointer = strndup $string, $max;
116
117       The same as "strdup" above, except at most $max characters will be
118       copied in the new string.
119

SEE ALSO

121       FFI::Platypus
122           Main Platypus documentation.
123

AUTHOR

125       Author: Graham Ollis <plicease@cpan.org>
126
127       Contributors:
128
129       Bakkiaraj Murugesan (bakkiaraj)
130
131       Dylan Cali (calid)
132
133       pipcet
134
135       Zaki Mughal (zmughal)
136
137       Fitz Elliott (felliott)
138
139       Vickenty Fesunov (vyf)
140
141       Gregor Herrmann (gregoa)
142
143       Shlomi Fish (shlomif)
144
145       Damyan Ivanov
146
147       Ilya Pavlov (Ilya33)
148
149       Petr Písař (ppisar)
150
151       Mohammad S Anwar (MANWAR)
152
153       Håkon Hægland (hakonhagland, HAKONH)
154
155       Meredith (merrilymeredith, MHOWARD)
156
157       Diab Jerius (DJERIUS)
158
159       Eric Brine (IKEGAMI)
160
161       szTheory
162
163       José Joaquín Atria (JJATRIA)
164
165       Pete Houston (openstrike, HOUSTON)
166

168       This software is copyright (c) 2015-2022 by Graham Ollis.
169
170       This is free software; you can redistribute it and/or modify it under
171       the same terms as the Perl 5 programming language system itself.
172
173
174
175perl v5.38.0                      2023-07-20          FFI::Platypus::Memory(3)
Impressum