1ExtUtils::H2PM(3) User Contributed Perl Documentation ExtUtils::H2PM(3)
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 $name
35 Sets the name of the perl module to generate. This will apply a
36 "package" header.
37 include $file
39 Adds a file to the list of headers which will be included by the C
40 program, to obtain the constants or structures from
41 constant $name, %args
43 Adds a numerical constant.
44 The following additional named arguments are also recognised:
46 • name => STRING
48 Use the given name for the generated constant function. If not
50 specified, the C name for the constant will be used.
51 • ifdef => STRING
53 If present, guard the constant with an "#ifdef STRING"
55 preprocessor macro. If the given string is not defined, no
56 constant will be generated.
57 structure $name, %args
59 Adds a structure definition. This requires a named argument, "members".
60 This should be an ARRAY ref containing an even number of name-
61 definition pairs. The first of each pair should be a member name. The
62 second should be one of the following structure member definitions.
63 The following additional named arguments are also recognised:
65 • pack_func => STRING
67 • unpack_func => STRING
69 Use the given names for the generated pack or unpack functions.
71 • with_tail => BOOL
73 If true, the structure is a header with more data behind it.
75 The pack function takes an optional extra string value for the
76 data tail, and the unpack function will return an extra string
77 value containing it.
78 • no_length_check => BOOL
80 If true, the generated unpack function will not first check the
82 length of its argument before attempting to unpack it. If the
83 buffer is not long enough to unpack all the required values,
84 the remaining ones will not be returned. This may be useful,
85 for example, in cases where various versions of a structure
86 have been designed, later versions adding extra members, but
87 where the exact version found may not be easy to determine
88 beforehand.
89 • arg_style => STRING
91 Defines the style in which the functions take arguments or
93 return values. Defaults to "list", which take or return a list
94 of values in the given order. The other allowed value is
95 "hashref", where the pack function takes a HASH reference and
96 the unpack function returns one. Each will consist of keys
97 named after the structure members. If a data tail is included,
98 it will use the hash key of "_tail".
99 • ifdef => STRING
101 If present, guard the structure with an "#ifdef STRING"
103 preprocessor macro. If the given string is not defined, no
104 functions will be generated.
105 The following structure member definitions are allowed:
107 • member_numeric
109 The field contains a single signed or unsigned number. Its size
111 and signedness will be automatically detected.
112 • member_strarray
114 The field contains a NULL-padded string of characters. Its size
116 will be automatically detected.
117 • member_constant($code)
119 The field contains a single number as for "member_numeric".
121 Instead of consuming/returning a value in the arguments list,
122 this member will be packed from an expression, or asserted that
123 it contains the given value. The string $code will be inserted
124 into the generated pack and unpack functions, so it can be used
125 for constants generated by the "constant" directive.
126 The structure definition results in two new functions being created,
128 "pack_$name" and "unpack_$name", where $name is the name of the
129 structure (with the leading "struct" prefix stripped). These behave
130 similarly to the familiar functions such as "pack_sockaddr_in"; the
131 "pack_" function will take a list of fields and return a packed string,
132 the "unpack_" function will take a string and return a list of fields.
133 no_export, use_export, use_export_ok
135 Controls the export behaviour of the generated symbols. "no_export"
136 creates symbols that are not exported by their package, they must be
137 used fully- qualified. "use_export" creates symbols that are exported
138 by default. "use_export_ok" creates symbols that are exported if they
139 are specifically requested at "use" time.
140 The mode can be changed at any time to affect only the symbols that
142 follow it. It defaults to "use_export_ok".
143 $perl = gen_output
145 Returns the generated perl code. This is used internally for testing
146 purposes but normally would not be necessary; see instead
147 "write_output".
148 write_output $filename
150 Write the generated perl code into the named file. This would normally
151 be used as the last function in the containing script, to generate the
152 output file. In the case of "ExtUtils::MakeMaker" or "Module::Build"
153 invoking the script, the path to the file to be generated should be
154 given in $ARGV[0]. Normally, therefore, the script would end with
155 write_output $ARGV[0];
157 include_path
159 Adds an include path to the list of paths used by the compiler
160 include_path $path
162 define
164 Adds a symbol to be defined on the compiler's commandline, by using the
165 "-D" option. This is sometimes required to turn on particular optional
166 parts of the included files. An optional value can also be specified.
167 define $symbol
169 define $symbol, $value;
170
172 Normally this module would be used by another module at build time, to
173 construct the relevant constants and structure functions from system
174 headers.
175 For example, suppose your operating system defines a new type of
177 socket, which has its own packet and address families, and perhaps some
178 new socket options which are valid on this socket. We can build a
179 module to contain the relevant constants and structure functions by
180 writing, for example:
181 #!/usr/bin/perl
183 use ExtUtils::H2PM;
185 module "Socket::Moonlaser";
187 include "moon/laser.h";
189 constant "AF_MOONLASER";
191 constant "PF_MOONLASER";
192 constant "SOL_MOONLASER";
194 constant "MOONLASER_POWER", name => "POWER";
196 constant "MOONLASER_WAVELENGTH", name => "WAVELENGTH";
197 structure "struct laserwl",
199 members => [
200 lwl_nm_coarse => member_numeric,
201 lwl_nm_fine => member_numeric,
202 ];
203 write_output $ARGV[0];
205 If we save this script as, say, lib/Socket/Moonlaser.pm.PL, then when
207 the distribution is built, the script will be used to generate the
208 contents of the file lib/Socket/Moonlaser.pm. Once installed, any other
209 code can simply
210 use Socket::Moonlaser qw( AF_MOONLASER );
212 to import a constant.
214 The method described above doesn't allow us any room to actually
216 include other code in the module. Perhaps, as well as these simple
217 constants, we'd like to include functions, documentation, etc... To
218 allow this, name the script instead something like
219 lib/Socket/Moonlaser_const.pm.PL, so that this is the name used for the
220 generated output. The code can then be included in the actual
221 lib/Socket/Moonlaser.pm (which will just be a normal perl module) by
222 package Socket::Moonlaser;
224 use Socket::Moonlaser_const;
226 sub get_power
228 {
229 getsockopt( $_[0], SOL_MOONLASER, POWER );
230 }
231 sub set_power
233 {
234 setsockopt( $_[0], SOL_MOONLASER, POWER, $_[1] );
235 }
236 sub get_wavelength
238 {
239 my $wl = getsockopt( $_[0], SOL_MOONLASER, WAVELENGTH );
240 defined $wl or return;
241 unpack_laserwl( $wl );
242 }
243 sub set_wavelength
245 {
246 my $wl = pack_laserwl( $_[1], $_[2] );
247 setsockopt( $_[0], SOL_MOONLASER, WAVELENGTH, $wl );
248 }
249 1;
251 Sometimes, the actual C structure layout may not exactly match the
253 semantics we wish to present to perl modules using this extension
254 wrapper. Socket address structures typically contain their address
255 family as the first member, whereas this detail isn't exposed by, for
256 example, the "sockaddr_in" and "sockaddr_un" functions. To cope with
257 this case, the low-level structure packing and unpacking functions can
258 be generated with a different name, and wrapped in higher-level
259 functions in the main code. For example, in Moonlaser_const.pm.PL:
260 no_export;
262 structure "struct sockaddr_ml",
264 pack_func => "_pack_sockaddr_ml",
265 unpack_func => "_unpack_sockaddr_ml",
266 members => [
267 ml_family => member_numeric,
268 ml_lat_deg => member_numeric,
269 ml_long_deg => member_numeric,
270 ml_lat_fine => member_numeric,
271 ml_long_fine => member_numeric,
272 ];
273 This will generate a pack/unpack function pair taking or returning five
275 arguments; these functions will not be exported. In our main
276 Moonlaser.pm file we can wrap these to actually expose a different API:
277 sub pack_sockaddr_ml
279 {
280 @_ == 2 or croak "usage: pack_sockaddr_ml(lat, long)";
281 my ( $lat, $long ) = @_;
282 return _pack_sockaddr_ml( AF_MOONLASER, int $lat, int $long,
284 ($lat - int $lat) * 1_000_000, ($long - int $long) * 1_000_000);
285 }
286 sub unpack_sockaddr_ml
288 {
289 my ( $family, $lat, $long, $lat_fine, $long_fine ) =
290 _unpack_sockaddr_ml( $_[0] );
291 $family == AF_MOONLASER or croak "expected family AF_MOONLASER";
293 return ( $lat + $lat_fine/1_000_000, $long + $long_fine/1_000_000 );
295 }
296 Sometimes, a structure will contain members which are themselves
298 structures. Suppose a different definition of the above address, which
299 at the C layer is defined as
300 struct angle
302 {
303 short deg;
304 unsigned long fine;
305 };
306 struct sockaddr_ml
308 {
309 short ml_family;
310 struct angle ml_lat, ml_long;
311 };
312 We can instead "flatten" this structure tree to obtain the five fields
314 by naming the sub-members of the outer structure:
315 structure "struct sockaddr_ml",
317 members => [
318 "ml_family" => member_numeric,
319 "ml_lat.deg" => member_numeric,
320 "ml_lat.fine" => member_numeric,
321 "ml_long.deg" => member_numeric,
322 "ml_long.fine" => member_numeric,
323 ];
324
326 • Consider more structure members. With strings comes the requirement
327 to have members that store a size. This requires cross-referential
328 members. And while we're at it it might be nice to have constant
329 members; fill in constants without consuming arguments when
330 packing, assert the right value on unpacking.
331
333 Paul Evans <leonerd@leonerd.org.uk>
334perl v5.36.0 2023-01-20 ExtUtils::H2PM(3)