1ExtUtils::H2PM(3)     User Contributed Perl Documentation    ExtUtils::H2PM(3)
2
3
4

NAME

6       "ExtUtils::H2PM" - automatically generate perl modules to wrap C header
7       files
8

DESCRIPTION

10       This module assists in generating wrappers around system
11       functionallity, such as "socket()" types or "ioctl()" calls, where the
12       only 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
20       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
26       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

FUNCTIONS

34   module $name
35       Sets the name of the perl module to generate. This will apply a
36       "package" header.
37
38   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
42   constant $name, %args
43       Adds a numerical constant.
44
45       The following additional named arguments are also recognised:
46
47       •       name => STRING
48
49               Use the given name for the generated constant function. If not
50               specified, the C name for the constant will be used.
51
52       •       ifdef => STRING
53
54               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
58   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
64       The following additional named arguments are also recognised:
65
66       •       pack_func => STRING
67
68       •       unpack_func => STRING
69
70               Use the given names for the generated pack or unpack functions.
71
72       •       with_tail => BOOL
73
74               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
79       •       no_length_check => BOOL
80
81               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
90       •       arg_style => STRING
91
92               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
100       •       ifdef => STRING
101
102               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
106       The following structure member definitions are allowed:
107
108       •       member_numeric
109
110               The field contains a single signed or unsigned number. Its size
111               and signedness will be automatically detected.
112
113       •       member_strarray
114
115               The field contains a NULL-padded string of characters. Its size
116               will be automatically detected.
117
118       •       member_constant($code)
119
120               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
127       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
134   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
141       The mode can be changed at any time to affect only the symbols that
142       follow it. It defaults to "use_export_ok".
143
144   $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
149   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
156        write_output $ARGV[0];
157
158   include_path
159       Adds an include path to the list of paths used by the compiler
160
161        include_path $path
162
163   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
168        define $symbol
169        define $symbol, $value;
170

EXAMPLES

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
176       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
182        #!/usr/bin/perl
183
184        use ExtUtils::H2PM;
185
186        module "Socket::Moonlaser";
187
188        include "moon/laser.h";
189
190        constant "AF_MOONLASER";
191        constant "PF_MOONLASER";
192
193        constant "SOL_MOONLASER";
194
195        constant "MOONLASER_POWER",      name => "POWER";
196        constant "MOONLASER_WAVELENGTH", name => "WAVELENGTH";
197
198        structure "struct laserwl",
199           members => [
200              lwl_nm_coarse => member_numeric,
201              lwl_nm_fine   => member_numeric,
202           ];
203
204        write_output $ARGV[0];
205
206       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
211        use Socket::Moonlaser qw( AF_MOONLASER );
212
213       to import a constant.
214
215       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
223        package Socket::Moonlaser;
224
225        use Socket::Moonlaser_const;
226
227        sub get_power
228        {
229           getsockopt( $_[0], SOL_MOONLASER, POWER );
230        }
231
232        sub set_power
233        {
234           setsockopt( $_[0], SOL_MOONLASER, POWER, $_[1] );
235        }
236
237        sub get_wavelength
238        {
239           my $wl = getsockopt( $_[0], SOL_MOONLASER, WAVELENGTH );
240           defined $wl or return;
241           unpack_laserwl( $wl );
242        }
243
244        sub set_wavelength
245        {
246           my $wl = pack_laserwl( $_[1], $_[2] );
247           setsockopt( $_[0], SOL_MOONLASER, WAVELENGTH, $wl );
248        }
249
250        1;
251
252       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
261        no_export;
262
263        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
274       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
278        sub pack_sockaddr_ml
279        {
280           @_ == 2 or croak "usage: pack_sockaddr_ml(lat, long)";
281           my ( $lat, $long ) = @_;
282
283           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
287        sub unpack_sockaddr_ml
288        {
289           my ( $family, $lat, $long, $lat_fine, $long_fine ) =
290              _unpack_sockaddr_ml( $_[0] );
291
292           $family == AF_MOONLASER or croak "expected family AF_MOONLASER";
293
294           return ( $lat + $lat_fine/1_000_000, $long + $long_fine/1_000_000 );
295        }
296
297       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
301        struct angle
302        {
303           short         deg;
304           unsigned long fine;
305        };
306
307        struct sockaddr_ml
308        {
309           short        ml_family;
310           struct angle ml_lat, ml_long;
311        };
312
313       We can instead "flatten" this structure tree to obtain the five fields
314       by naming the sub-members of the outer structure:
315
316        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

TODO

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

AUTHOR

333       Paul Evans <leonerd@leonerd.org.uk>
334
335
336
337perl v5.34.0                      2022-01-21                 ExtUtils::H2PM(3)
Impressum