1Inline::C(3)          User Contributed Perl Documentation         Inline::C(3)
2
3
4

NAME

6       Inline::C - C Language Support for Inline
7

VERSION

9       This document describes Inline::C version 0.82.
10

DESCRIPTION

12       "Inline::C" is a module that allows you to write Perl subroutines in C.
13       Since version 0.30 the Inline module supports multiple programming
14       languages and each language has its own support module. This document
15       describes how to use Inline with the C programming language. It also
16       goes a bit into Perl C internals.
17
18       If you want to start working with programming examples right away,
19       check out Inline::C::Cookbook. For more information on Inline in
20       general, see Inline.
21

USAGE

23       You never actually use "Inline::C" directly. It is just a support
24       module for using "Inline.pm" with C. So the usage is always:
25
26           use Inline C => ...;
27
28       or
29
30           bind Inline C => ...;
31

FUNCTION DEFINITIONS

33       The Inline grammar for C recognizes certain function definitions (or
34       signatures) in your C code. If a signature is recognized by Inline,
35       then it will be available in Perl-space. That is, Inline will generate
36       the "glue" necessary to call that function as if it were a Perl
37       subroutine. If the signature is not recognized, Inline will simply
38       ignore it, with no complaints.  It will not be available from Perl-
39       space, although it will be available from C-space.
40
41       Inline looks for ANSI/prototype style function definitions. They must
42       be of the form:
43
44           return-type function-name ( type-name-pairs ) { ... }
45
46       The most common types are: "int", "long", "double", "char*", and "SV*".
47       But you can use any type for which Inline can find a typemap. Inline
48       uses the "typemap" file distributed with Perl as the default. You can
49       specify more typemaps with the "typemaps" configuration option.
50
51       A return type of "void" may also be used. The following are examples of
52       valid function definitions.
53
54           int Foo(double num, char* str) {
55           void Foo(double num, char* str) {
56           void Foo(SV*, ...) {
57           long Foo(int i, int j, ...) {
58           SV* Foo(void) { # 'void' arg invalid with the ParseRecDescent parser.
59                           # Works only with the ParseRegExp parser.
60                           # See the section on `using` (below).
61           SV* Foo() {  # Alternative to specifying 'void' arg. Is valid with
62                        # both the ParseRecDescent and ParseRegExp parsers.
63
64       The following definitions would not be recognized:
65
66           Foo(int i) {               # no return type
67           int Foo(float f) {         # no (default) typemap for float
68           int Foo(num, str) double num; char* str; {
69
70       Notice that Inline only looks for function definitions, not function
71       prototypes. Definitions are the syntax directly preceding a function
72       body.  Also Inline does not scan external files, like headers. Only the
73       code passed to Inline is used to create bindings; although other
74       libraries can linked in, and called from C-space.
75

C CONFIGURATION OPTIONS

77       For information on how to specify Inline configuration options, see
78       Inline.  This section describes each of the configuration options
79       available for C. Most of the options correspond either to MakeMaker or
80       XS options of the same name.  See ExtUtils::MakeMaker and perlxs.
81
82       "auto_include"
83           Specifies extra statements to automatically included. They will be
84           added onto the defaults. A newline char will be automatically
85           added.
86
87               use Inline C => config => auto_include => '#include "yourheader.h"';
88
89       "autowrap"
90           If you "enable => autowrap", Inline::C will parse function
91           declarations (prototype statements) in your C code. For each
92           declaration it can bind to, it will create a dummy wrapper that
93           will call the real function which may be in an external library.
94           This is a nice convenience for functions that would otherwise just
95           require an empty wrapper function.
96
97           This is similar to the base functionality you get from "h2xs". It
98           can be very useful for binding to external libraries.
99
100       "boot"
101           Specifies C code to be executed in the XS "BOOT" section.
102           Corresponds to the XS parameter.
103
104       "cc"
105           Specify which compiler to use.
106
107       "ccflags"
108           Specify compiler flags - same as ExtUtils::MakeMaker's "CCFLAGS"
109           option.  Whatever gets specified here replaces the default
110           $Config{ccflags}. Often, you'll want to add an extra flag or two
111           without clobbering the default flags in which case you could
112           instead use "ccflagsex" (see below) or, if Config.pm has already
113           been loaded:
114
115               use Inline C => Config => ccflags => $Config{ccflags} . " -DXTRA -DTOO";
116
117       "ccflagsex"
118           Extend compiler flags. Sets "CCFLAGS" to $Config{ccflags} followed
119           by a space, followed by the specified value:
120
121               use Inline C => config => ccflagsex => "-DXTRA -DTOO";
122
123       "cppflags"
124
125       Specify preprocessor flags. Passed to "cpp" C preprocessor by
126       Preprocess() in Inline::Filters.
127
128           use Inline C => <<'END',
129               CPPFLAGS => ' -DPREPROCESSOR_DEFINE',
130               FILTERS => 'Preprocess';
131           use Inline C => <<'END',
132               CPPFLAGS => ' -DPREPROCESSOR_DEFINE=4321',
133               FILTERS => 'Preprocess';
134
135       "filters"
136           Allows you to specify a list of source code filters. If more than
137           one is requested, be sure to group them with an array ref. The
138           filters can either be subroutine references or names of filters
139           provided by the supplementary Inline::Filters module.
140
141           Your source code will be filtered just before it is parsed by
142           Inline. The MD5 fingerprint is generated before filtering. Source
143           code filters can be used to do things like stripping out POD
144           documentation, pre-expanding "#include" statements or whatever else
145           you please. For example:
146
147               use Inline C => DATA =>
148                          filters => [Strip_POD => \&MyFilter => Preprocess ];
149
150           Filters are invoked in the order specified. See Inline::Filters for
151           more information.
152
153           If a filter is an array reference, it is assumed to be a usage of a
154           filter plug- in named by the first element of that array reference.
155           The rest of the elements of the array reference are used as
156           arguments to the filter. For example, consider a "filters"
157           parameter like this:
158
159               use Inline C => DATA => filters => [ [ Ragel => '-G2' ] ];
160
161           In order for Inline::C to process this filter, it will attempt to
162           require the module Inline::Filters::Ragel and will then call the
163           "filter" function in that package with the argument '-G2'. This
164           function will return the actual filtering function.
165
166       "inc"
167           Specifies an include path to use. Corresponds to the MakeMaker
168           parameter.  Expects a fully qualified path.
169
170               use Inline C => config => inc => '-I/inc/path';
171
172       "ld"
173           Specify which linker to use.
174
175       "lddlflags"
176           Specify which linker flags to use.
177
178           NOTE: These flags will completely override the existing flags,
179           instead of
180                 just adding to them. So if you need to use those too, you
181           must
182                 respecify them here.
183
184       "libs"
185           Specifies external libraries that should be linked into your code.
186           Corresponds to the MakeMaker parameter. Provide a fully qualified
187           path with the "-L" switch if the library is in a location where it
188           won't be found automatically.
189
190               use Inline C => config => libs => '-lyourlib';
191
192           or
193
194               use Inline C => config => libs => '-L/your/path -lyourlib';
195
196       "make"
197           Specify the name of the 'make' utility to use.
198
199       "myextlib"
200           Specifies a user compiled object that should be linked in.
201           Corresponds to the MakeMaker parameter. Expects a fully qualified
202           path.
203
204               use Inline C => config => myextlib => '/your/path/yourmodule.so';
205
206       "optimize"
207           This controls the MakeMaker "OPTIMIZE" setting. By setting this
208           value to '-g', you can turn on debugging support for your Inline
209           extensions. This will allow you to be able to set breakpoints in
210           your C code using a debugger like gdb.
211
212       "prefix"
213           Specifies a prefix that will be automatically stripped from C
214           functions when they are bound to Perl. Useful for creating wrappers
215           for shared library API-s, and binding to the original names in
216           Perl. Also useful when names conflict with Perl internals.
217           Corresponds to the XS parameter.
218
219               use Inline C => config => prefix => 'ZLIB_';
220
221       "pre_head"
222           Specifies code that will precede the inclusion of all files
223           specified in "auto_include" (ie "EXTERN.h", "perl.h", "XSUB.h",
224           "INLINE.h" and anything else that might have been added to
225           "auto_include" by the user). If the specified value identifies a
226           file, the contents of that file will be inserted, otherwise the
227           specified value is inserted.
228
229               use Inline C => config => pre_head => $code_or_filename;
230
231       "prototype"
232           Corresponds to the XS keyword 'PROTOTYPE'. See the perlxs
233           documentation for both 'PROTOTYPES' and 'PROTOTYPE'. As an example,
234           the following will set the PROTOTYPE of the 'foo' function to '$',
235           and disable prototyping for the 'bar' function.
236
237               use Inline C => config => prototype => {foo => '$', bar => 'DISABLE'}
238
239       "prototypes"
240           Corresponds to the XS keyword 'PROTOTYPES'. Can take only values of
241           'ENABLE' or 'DISABLE'. (Contrary to XS, default value is
242           'DISABLE'). See the perlxs documentation for both 'PROTOTYPES' and
243           'PROTOTYPE'.
244
245               use Inline C => config => prototypes => 'ENABLE';
246
247       "typemaps"
248           Specifies extra typemap files to use. These types will modify the
249           behaviour of the C parsing. Corresponds to the MakeMaker parameter.
250           Specify either a fully qualified path or a path relative to the cwd
251           (ie relative to what the cwd is at the time the script is loaded).
252
253               use Inline C => config => typemaps => '/your/path/typemap';
254
255       "using"
256           Specifies which parser to use. The default is
257           Inline::C::Parser::RecDescent, which uses the Parse::RecDescent
258           module.
259
260           The other options are "::Parser::Pegex" and "::Parser::RegExp",
261           which uses the Inline::C::Parser::Pegex and
262           Inline::C::Parser::RegExp modules that ship with Inline::C.
263
264               use Inline C => config => using => '::Parser::Pegex';
265
266           Note that the following old options are deprecated, but still work
267           at this time:
268
269           •   "ParseRecDescent"
270
271           •   "ParseRegExp"
272
273           •   "ParsePegex"
274

C-PERL BINDINGS

276       This section describes how the "Perl" variables get mapped to "C"
277       variables and back again.
278
279       First, you need to know how "Perl" passes arguments back and forth to
280       subroutines. Basically it uses a stack (also known as the Stack). When
281       a sub is called, all of the parenthesized arguments get expanded into a
282       list of scalars and pushed onto the Stack. The subroutine then pops all
283       of its parameters off of the Stack. When the sub is done, it pushes all
284       of its return values back onto the Stack.
285
286       The Stack is an array of scalars known internally as "SV"'s. The Stack
287       is actually an array of pointers to SV or "SV*"; therefore every
288       element of the Stack is natively a "SV*". For FMTYEWTK about this, read
289       "perldoc perlguts".
290
291       So back to variable mapping. XS uses a thing known as "typemaps" to
292       turn each "SV*" into a "C" type and back again. This is done through
293       various XS macro calls, casts and the Perl API. See "perldoc perlapi".
294       XS allows you to define your own typemaps as well for fancier non-
295       standard types such as "typedef"- ed structs.
296
297       Inline uses the default Perl typemap file for its default types. This
298       file is called "/usr/local/lib/perl5/5.6.1/ExtUtils/typemap", or
299       something similar, depending on your Perl installation. It has
300       definitions for over 40 types, which are automatically used by Inline.
301       (You should probably browse this file at least once, just to get an
302       idea of the possibilities.)
303
304       Inline parses your code for these types and generates the XS code to
305       map them.  The most commonly used types are:
306
307       •   "int"
308
309       •   "long"
310
311       •   "double"
312
313       •   "char*"
314
315       •   "void"
316
317       •   "SV*"
318
319       If you need to deal with a type that is not in the defaults, just use
320       the generic "SV*" type in the function definition. Then inside your
321       code, do the mapping yourself. Alternatively, you can create your own
322       typemap files and specify them using the "typemaps" configuration
323       option.
324
325       A return type of "void" has a special meaning to Inline. It means that
326       you plan to push the values back onto the Stack yourself. This is what
327       you need to do to return a list of values. If you really don't want to
328       return anything (the traditional meaning of "void") then simply don't
329       push anything back.
330
331       If ellipsis or "..." is used at the end of an argument list, it means
332       that any number of "SV*"s may follow. Again you will need to pop the
333       values off of the "Stack" yourself.
334
335       See "EXAMPLES" below.
336

THE INLINE STACK MACROS

338       When you write Inline C, the following lines are automatically
339       prepended to your code (by default):
340
341           #include "EXTERN.h"
342           #include "perl.h"
343           #include "XSUB.h"
344           #include "INLINE.h"
345
346       The file "INLINE.h" defines a set of macros that are useful for
347       handling the Perl Stack from your C functions.
348
349       "Inline_Stack_Vars"
350           You'll need to use this one, if you want to use the others. It sets
351           up a few local variables: "sp", "items", "ax" and "mark", for use
352           by the other macros. It's not important to know what they do, but I
353           mention them to avoid possible name conflicts.
354
355           NOTE: Since this macro declares variables, you'll need to put it
356           with your
357                 other variable declarations at the top of your function. It
358           must
359                 come before any executable statements and before any other
360                 "Inline_Stack" macros.
361
362       "Inline_Stack_Items"
363           Returns the number of arguments passed in on the Stack.
364
365       Inline_Stack_Item(i)
366           Refers to a particular "SV*" in the Stack, where "i" is an index
367           number starting from zero. Can be used to get or set the value.
368
369       "Inline_Stack_Reset"
370           Use this before pushing anything back onto the Stack. It resets the
371           internal Stack pointer to the beginning of the Stack.
372
373       Inline_Stack_Push(sv)
374           Push a return value back onto the Stack. The value must be of type
375           "SV*".
376
377       "Inline_Stack_Done"
378           After you have pushed all of your return values, you must call this
379           macro.
380
381       Inline_Stack_Return(n)
382           Return "n" items on the Stack.
383
384       "Inline_Stack_Void"
385           A special macro to indicate that you really don't want to return
386           anything. Same as:
387
388               Inline_Stack_Return(0);
389
390           Please note that this macro actually returns from your function.
391
392       Each of these macros is available in 3 different styles to suit your
393       coding tastes. The following macros are equivalent.
394
395           Inline_Stack_Vars
396           inline_stack_vars
397           INLINE_STACK_VARS
398
399       All of this functionality is available through XS macro calls as well.
400       So why duplicate the functionality? There are a few reasons why I
401       decided to offer this set of macros. First, as a convenient way to
402       access the Stack.  Second, for consistent, self documenting, non-
403       cryptic coding. Third, for future compatibility. It occurred to me that
404       if a lot of people started using XS macros for their C code, the
405       interface might break under Perl6. By using this set, hopefully I will
406       be able to insure future compatibility of argument handling.
407
408       Of course, if you use the rest of the Perl API, your code will most
409       likely break under Perl6. So this is not a 100% guarantee. But since
410       argument handling is the most common interface you're likely to use, it
411       seemed like a wise thing to do.
412

WRITING C SUBROUTINES

414       The definitions of your C functions will fall into one of the following
415       four categories. For each category there are special considerations.
416
417       "int Foo(int arg1, char* arg2, SV* arg3) {"
418           This is the simplest case. You have a non "void" return type and a
419           fixed length argument list. You don't need to worry about much. All
420           the conversions will happen automatically.
421
422       "void Foo(int arg1, char* arg2, SV* arg3) {"
423           In this category you have a "void" return type. This means that
424           either you want to return nothing, or that you want to return a
425           list. In the latter case you'll need to push values onto the Stack
426           yourself. There are a few Inline macros that make this easy. Code
427           something like this:
428
429               int i, max; SV* my_sv[10];
430               Inline_Stack_Vars;
431               Inline_Stack_Reset;
432               for (i = 0; i < max; i++)
433                 Inline_Stack_Push(my_sv[i]);
434               Inline_Stack_Done;
435
436           After resetting the Stack pointer, this code pushes a series of
437           return values.  At the end it uses "Inline_Stack_Done" to mark the
438           end of the return stack.
439
440           If you really want to return nothing, then don't use the
441           "Inline_Stack_" macros. If you must use them, then set use
442           "Inline_Stack_Void" at the end of your function.
443
444       "char* Foo(SV* arg1, ...) {"
445           In this category you have an unfixed number of arguments. This
446           means that you'll have to pop values off the Stack yourself. Do it
447           like this:
448
449               int i;
450               Inline_Stack_Vars;
451               for (i = 0; i < Inline_Stack_Items; i++)
452                 handle_sv(Inline_Stack_Item(i));
453
454           The return type of Inline_Stack_Item(i) is "SV*".
455
456       "void* Foo(SV* arg1, ...) {"
457           In this category you have both a "void" return type and an unfixed
458           number of arguments. Just combine the techniques from Categories 3
459           and 4.
460

EXAMPLES

462       Here are a few examples. Each one is a complete program that you can
463       try running yourself. For many more examples see Inline::C::Cookbook.
464
465   Example #1 - Greetings
466       This example will take one string argument (a name) and print a
467       greeting. The function is called with a string and with a number. In
468       the second case the number is forced to a string.
469
470       Notice that you do not need to "#include <stdio.h">. The "perl.h"
471       header file which gets included by default, automatically loads the
472       standard C header files for you.
473
474           use Inline 'C';
475           greet('Ingy');
476           greet(42);
477           __END__
478           __C__
479           void greet(char* name) {
480             printf("Hello %s!\n", name);
481           }
482
483   Example #2 - and Salutations
484       This is similar to the last example except that the name is passed in
485       as a "SV*" (pointer to Scalar Value) rather than a string ("char*").
486       That means we need to convert the "SV" to a string ourselves. This is
487       accomplished using the "SvPVX" function which is part of the "Perl"
488       internal API. See "perldocperlapi" for more info.
489
490       One problem is that "SvPVX" doesn't automatically convert strings to
491       numbers, so we get a little surprise when we try to greet 42. The
492       program segfaults, a common occurrence when delving into the guts of
493       Perl.
494
495           use Inline 'C';
496           greet('Ingy');
497           greet(42);
498           __END__
499           __C__
500           void greet(SV* sv_name) {
501             printf("Hello %s!\n", SvPVX(sv_name));
502           }
503
504   Example #3 - Fixing the problem
505       We can fix the problem in Example #2 by using the "SvPV" function
506       instead.  This function will stringify the "SV" if it does not contain
507       a string.  "SvPV" returns the length of the string as it's second
508       parameter. Since we don't care about the length, we can just put
509       "PL_na" there, which is a special variable designed for that purpose.
510
511           use Inline 'C';
512           greet('Ingy');
513           greet(42);
514           __END__
515           __C__
516           void greet(SV* sv_name) {
517             printf("Hello %s!\n", SvPV(sv_name, PL_na));
518           }
519

SEE ALSO

521       For general information about Inline see Inline.
522
523       For sample programs using Inline with C see Inline::C::Cookbook.
524
525       For information on supported languages and platforms see Inline-
526       Support.
527
528       For information on writing your own Inline Language Support Module, see
529       Inline-API.
530
531       Inline's mailing list is inline@perl.org
532
533       To subscribe, send email to inline-subscribe@perl.org
534

BUGS AND DEFICIENCIES

536       If you use C function names that happen to be used internally by Perl,
537       you will get a load error at run time. There is currently no
538       functionality to prevent this or to warn you. For now, a list of Perl's
539       internal symbols is packaged in the Inline module distribution under
540       the filename 'symbols.perl'. Avoid using these in your code.
541

AUTHORS

543       Ingy döt Net <ingy@cpan.org>
544
545       Sisyphus <sisyphus@cpan.org>
546
548       Copyright 2000-2022. Ingy döt Net.
549
550       Copyright 2008, 2010-2014. Sisyphus.
551
552       This program is free software; you can redistribute it and/or modify it
553       under the same terms as Perl itself.
554
555       See <http://www.perl.com/perl/misc/Artistic.html>
556
557
558
559perl v5.36.0                      2023-01-31                      Inline::C(3)
Impressum