1ExtUtils::H2PM(3pm) User Contributed Perl Documentation ExtUtils::H2PM(3pm)
2
6 "ExtUtils::H2PM" - automatically generate perl modules to wrap C header
7 files
8
10 This module assists in generating wrappers around system
11 functionallity, such as socket() types or ioctl() calls, where the only
12 interesting features required are the values of some constants or
13 layouts of structures normally only known to the C header files. Rather
14 than writing an entire XS module just to contain some constants and
15 pack/unpack functions, this module allows the author to generate, at
16 module build time, a pure perl module containing constant declarations
17 and structure utility functions. The module then requires no XS module
18 to be loaded at run time.
19 In comparison to h2ph, "C::Scan::Constants", and so on, this module
21 works by generating a small C program containing printf() lines to
22 output the values of the constants, compiling it, and running it. This
23 allows it to operate without needing tricky syntax parsing or guessing
24 of the contents of C header files.
25 It can also automatically build pack/unpack functions for simple
27 structure layouts, whose members are all simple integer or character
28 array fields. It is not intended as a full replacement of arbitrary
29 code written in XS modules. If structures should contain pointers, or
30 require special custom handling, then likely an XS module will need to
31 be written.
32
34 module
35 module $name;
36 Sets the name of the perl module to generate. This will apply a
38 "package" header.
39 include
41 include $file;
42 Adds a file to the list of headers which will be included by the C
44 program, to obtain the constants or structures from
45 constant
47 constant $name, %args;
48 Adds a numerical constant.
50 The following additional named arguments are also recognised:
52 • name => STRING
54 Use the given name for the generated constant function. If not
56 specified, the C name for the constant will be used.
57 • ifdef => STRING
59 If present, guard the constant with an "#ifdef STRING" preprocessor
61 macro. If the given string is not defined, no constant will be
62 generated.
63 structure
65 structure $name, %args;
66 Adds a structure definition. This requires a named argument, "members".
68 This should be an ARRAY ref containing an even number of name-
69 definition pairs. The first of each pair should be a member name. The
70 second should be one of the following structure member definitions.
71 The following additional named arguments are also recognised:
73 • pack_func => STRING
75 • unpack_func => STRING
77 Use the given names for the generated pack or unpack functions.
79 • with_tail => BOOL
81 If true, the structure is a header with more data behind it. The
83 pack function takes an optional extra string value for the data
84 tail, and the unpack function will return an extra string value
85 containing it.
86 • no_length_check => BOOL
88 If true, the generated unpack function will not first check the
90 length of its argument before attempting to unpack it. If the
91 buffer is not long enough to unpack all the required values, the
92 remaining ones will not be returned. This may be useful, for
93 example, in cases where various versions of a structure have been
94 designed, later versions adding extra members, but where the exact
95 version found may not be easy to determine beforehand.
96 • arg_style => STRING
98 Defines the style in which the functions take arguments or return
100 values. Defaults to "list", which take or return a list of values
101 in the given order. The other allowed value is "hashref", where
102 the pack function takes a HASH reference and the unpack function
103 returns one. Each will consist of keys named after the structure
104 members. If a data tail is included, it will use the hash key of
105 "_tail".
106 • ifdef => STRING
108 If present, guard the structure with an "#ifdef STRING"
110 preprocessor macro. If the given string is not defined, no
111 functions will be generated.
112 The following structure member definitions are allowed:
114 • member_numeric
116 The field contains a single signed or unsigned number. Its size and
118 signedness will be automatically detected.
119 • member_strarray
121 The field contains a NULL-padded string of characters. Its size
123 will be automatically detected.
124 • member_constant($code)
126 The field contains a single number as for "member_numeric". Instead
128 of consuming/returning a value in the arguments list, this member
129 will be packed from an expression, or asserted that it contains the
130 given value. The string $code will be inserted into the generated
131 pack and unpack functions, so it can be used for constants
132 generated by the "constant" directive.
133 The structure definition results in two new functions being created,
135 "pack_$name" and "unpack_$name", where $name is the name of the
136 structure (with the leading "struct" prefix stripped). These behave
137 similarly to the familiar functions such as "pack_sockaddr_in"; the
138 "pack_" function will take a list of fields and return a packed string,
139 the "unpack_" function will take a string and return a list of fields.
140 no_export
142 use_export
143 use_export_ok
144 no_export;
145 use_export;
146 use_export_ok;
147 Controls the export behaviour of the generated symbols. "no_export"
149 creates symbols that are not exported by their package, they must be
150 used fully- qualified. "use_export" creates symbols that are exported
151 by default. "use_export_ok" creates symbols that are exported if they
152 are specifically requested at "use" time.
153 The mode can be changed at any time to affect only the symbols that
155 follow it. It defaults to "use_export_ok".
156 gen_output
158 $perl = gen_output;
159 Returns the generated perl code. This is used internally for testing
161 purposes but normally would not be necessary; see instead
162 "write_output".
163 write_output
165 write_output $filename;
166 Write the generated perl code into the named file. This would normally
168 be used as the last function in the containing script, to generate the
169 output file. In the case of "ExtUtils::MakeMaker" or "Module::Build"
170 invoking the script, the path to the file to be generated should be
171 given in $ARGV[0]. Normally, therefore, the script would end with
172 write_output $ARGV[0];
174 include_path
176 include_path $path
177 Adds an include path to the list of paths used by the compiler
179 define
181 define $symbol;
182 define $symbol, $value;
183 Adds a symbol to be defined on the compiler's commandline, by using the
185 "-D" option. This is sometimes required to turn on particular optional
186 parts of the included files. An optional value can also be specified.
187
189 Normally this module would be used by another module at build time, to
190 construct the relevant constants and structure functions from system
191 headers.
192 For example, suppose your operating system defines a new type of
194 socket, which has its own packet and address families, and perhaps some
195 new socket options which are valid on this socket. We can build a
196 module to contain the relevant constants and structure functions by
197 writing, for example:
198 #!/usr/bin/perl
200 use ExtUtils::H2PM;
202 module "Socket::Moonlaser";
204 include "moon/laser.h";
206 constant "AF_MOONLASER";
208 constant "PF_MOONLASER";
209 constant "SOL_MOONLASER";
211 constant "MOONLASER_POWER", name => "POWER";
213 constant "MOONLASER_WAVELENGTH", name => "WAVELENGTH";
214 structure "struct laserwl",
216 members => [
217 lwl_nm_coarse => member_numeric,
218 lwl_nm_fine => member_numeric,
219 ];
220 write_output $ARGV[0];
222 If we save this script as, say, lib/Socket/Moonlaser.pm.PL, then when
224 the distribution is built, the script will be used to generate the
225 contents of the file lib/Socket/Moonlaser.pm. Once installed, any other
226 code can simply
227 use Socket::Moonlaser qw( AF_MOONLASER );
229 to import a constant.
231 The method described above doesn't allow us any room to actually
233 include other code in the module. Perhaps, as well as these simple
234 constants, we'd like to include functions, documentation, etc... To
235 allow this, name the script instead something like
236 lib/Socket/Moonlaser_const.pm.PL, so that this is the name used for the
237 generated output. The code can then be included in the actual
238 lib/Socket/Moonlaser.pm (which will just be a normal perl module) by
239 package Socket::Moonlaser;
241 use Socket::Moonlaser_const;
243 sub get_power
245 {
246 getsockopt( $_[0], SOL_MOONLASER, POWER );
247 }
248 sub set_power
250 {
251 setsockopt( $_[0], SOL_MOONLASER, POWER, $_[1] );
252 }
253 sub get_wavelength
255 {
256 my $wl = getsockopt( $_[0], SOL_MOONLASER, WAVELENGTH );
257 defined $wl or return;
258 unpack_laserwl( $wl );
259 }
260 sub set_wavelength
262 {
263 my $wl = pack_laserwl( $_[1], $_[2] );
264 setsockopt( $_[0], SOL_MOONLASER, WAVELENGTH, $wl );
265 }
266 1;
268 Sometimes, the actual C structure layout may not exactly match the
270 semantics we wish to present to perl modules using this extension
271 wrapper. Socket address structures typically contain their address
272 family as the first member, whereas this detail isn't exposed by, for
273 example, the "sockaddr_in" and "sockaddr_un" functions. To cope with
274 this case, the low-level structure packing and unpacking functions can
275 be generated with a different name, and wrapped in higher-level
276 functions in the main code. For example, in Moonlaser_const.pm.PL:
277 no_export;
279 structure "struct sockaddr_ml",
281 pack_func => "_pack_sockaddr_ml",
282 unpack_func => "_unpack_sockaddr_ml",
283 members => [
284 ml_family => member_numeric,
285 ml_lat_deg => member_numeric,
286 ml_long_deg => member_numeric,
287 ml_lat_fine => member_numeric,
288 ml_long_fine => member_numeric,
289 ];
290 This will generate a pack/unpack function pair taking or returning five
292 arguments; these functions will not be exported. In our main
293 Moonlaser.pm file we can wrap these to actually expose a different API:
294 sub pack_sockaddr_ml
296 {
297 @_ == 2 or croak "usage: pack_sockaddr_ml(lat, long)";
298 my ( $lat, $long ) = @_;
299 return _pack_sockaddr_ml( AF_MOONLASER, int $lat, int $long,
301 ($lat - int $lat) * 1_000_000, ($long - int $long) * 1_000_000);
302 }
303 sub unpack_sockaddr_ml
305 {
306 my ( $family, $lat, $long, $lat_fine, $long_fine ) =
307 _unpack_sockaddr_ml( $_[0] );
308 $family == AF_MOONLASER or croak "expected family AF_MOONLASER";
310 return ( $lat + $lat_fine/1_000_000, $long + $long_fine/1_000_000 );
312 }
313 Sometimes, a structure will contain members which are themselves
315 structures. Suppose a different definition of the above address, which
316 at the C layer is defined as
317 struct angle
319 {
320 short deg;
321 unsigned long fine;
322 };
323 struct sockaddr_ml
325 {
326 short ml_family;
327 struct angle ml_lat, ml_long;
328 };
329 We can instead "flatten" this structure tree to obtain the five fields
331 by naming the sub-members of the outer structure:
332 structure "struct sockaddr_ml",
334 members => [
335 "ml_family" => member_numeric,
336 "ml_lat.deg" => member_numeric,
337 "ml_lat.fine" => member_numeric,
338 "ml_long.deg" => member_numeric,
339 "ml_long.fine" => member_numeric,
340 ];
341
343 • Consider more structure members. With strings comes the requirement
344 to have members that store a size. This requires cross-referential
345 members. And while we're at it it might be nice to have constant
346 members; fill in constants without consuming arguments when
347 packing, assert the right value on unpacking.
348
350 Paul Evans <leonerd@leonerd.org.uk>
351perl v5.38.0 2023-07-20 ExtUtils::H2PM(3pm)