1Inline::C::Cookbook(3)User Contributed Perl DocumentationInline::C::Cookbook(3)
2
6 Inline::C::Cookbook - A Cornucopia of Inline C Recipes
7
9 It's a lot easier for most of us to cook a meal from a recipe, rather
10 than just throwing things into a pot until something edible forms. So
11 it is with programming as well. "Inline.pm" makes C programming for
12 Perl as easy as possible. Having a set of easy to understand samples,
13 makes it simpler yet.
14 This Cookbook is intended to be an evergrowing repository of small yet
16 complete coding examples; each showing how to accomplish a particular
17 task with Inline. Each example is followed by a short discussion,
18 explaining in detail the particular features that are being
19 demonstrated.
20 Many of these recipes are adapted from email discussions I have had
22 with Inline users around the world. It has been my experience so far,
23 that Inline provides an elegant solution to almost all problems
24 involving Perl and C.
25 Bon Appetit!
27
29 Hello, world
30 Problem
31 It seems that the first thing any programmer wants to do when he learns
33 a new programming technique is to use it to greet the Earth. How can I
34 do this using Inline?
35 Solution
37 use Inline C => <<'...';
38 void greet() {
40 printf("Hello, world\n");
41 }
42 ...
43 greet;
45 Discussion
47 Nothing too fancy here. We define a single C function "greet()"
48 which prints a message to STDOUT. One thing to note is that since
49 the Inline code comes before the function call to "greet", we can
50 call it as a bareword (no parentheses).
51 See Also
53 See Inline and Inline::C for basic info about "Inline.pm".
54 Credits
56 • Brian Kernigan
57 • Dennis Ritchie
59 One Liner
61 Problem
62 A concept is valid in Perl only if it can be shown to work in one
63 line. Can Inline reduce the complexities of Perl/C interaction to a
64 one-liner?
65 Solution
67 perl -e 'use Inline C=>q{void greet(){printf("Hello, world\n");}};greet'
68 Discussion
70 Try doing that in XS :-)
71 See Also
73 My email signature of late is:
74 perl -le 'use Inline C=>q{SV*JAxH(char*x){return newSVpvf("Just Another %s Hacker",x);}};print JAxH+Perl'
76 A bit fancier but a few bytes too long to qualify as a true one
78 liner :-(
79 Credits
81 "Eli the Bearded" <elijah@workspot.net> gave me the idea that I
82 should have an Inline one-liner as a signature.
83
85 Data Types
86 Problem
87 How do I pass different types of data to and from Inline C
88 functions; like strings, numbers and integers?
89 Solution
91 # vowels.pl
92 use Inline 'C';
93 $filename = $ARGV[0];
95 die "Usage: perl vowels.pl filename\n" unless -f $filename;
96 $text = join '', <>; # slurp input file
98 $vp = vowel_scan($text); # call our function
99 $vp = sprintf("%03.1f", $vp * 100); # format for printing
100 print "The letters in $filename are $vp% vowels.\n";
101 __END__
103 __C__
104 /* Find percentage of vowels to letters */
106 double vowel_scan(char* str) {
107 int letters = 0;
108 int vowels = 0;
109 int i = 0;
110 char c;
111 char normalize = 'a' ^ 'A';
112 /* normalize forces lower case in ASCII; upper in EBCDIC */
113 char A = normalize | 'a';
114 char E = normalize | 'e';
115 char I = normalize | 'i';
116 char O = normalize | 'o';
117 char U = normalize | 'u';
118 char Z = normalize | 'z';
119 while(c = str[i++]) {
121 c |= normalize;
122 if (c >= A && c <= Z) {
123 letters++;
124 if (c == A || c == E || c == I || c == O || c == U)
125 vowels++;
126 }
127 }
128 return letters ? ((double) vowels / letters) : 0.0;
130 }
131 Discussion
133 This script takes a file name from the command line and prints the
134 ratio of vowels to letters in that file. "vowels.pl" uses an Inline
135 C function called "vowel_scan", that takes a string argument, and
136 returns the percentage of vowels as a floating point number between
137 0 and 1. It handles upper and lower case letters, and works with
138 ASCII and EBCDIC. It is also quite fast.
139 Running this script produces:
141 > perl vowels.pl /usr/dict/words
143 The letters in /usr/dict/words are 37.5% vowels.
144 It is very important to note that the examples in this cookbook use
146 "char *" to mean a string. Internally Perl has various mechanisms
147 to deal with strings that contain characters with code points above
148 255, using Unicode. This means that naively treating strings as
149 "char *", an array of 8-bit characters, can lead to problems. You
150 need to be aware of this and consider using a UTF-8 library to deal
151 with strings.
152 See Also
154 The Perl Journal vol #19 has an article about Inline which uses
155 this example.
156 Credits
158 This example was reprinted by permission of The Perl Journal. It
159 was edited to work with Inline v0.30 and higher.
160 Variable Argument Lists
162 Problem
163 How do I pass a variable-sized list of arguments to an Inline C
165 function?
166 Solution
168 greet(qw(Sarathy Jan Sparky Murray Mike));
169 use Inline C => <<'END_OF_C_CODE';
171 void greet(SV* name1, ...) {
173 Inline_Stack_Vars;
174 int i;
175 for (i = 0; i < Inline_Stack_Items; i++)
177 printf("Hello %s!\n", SvPV(Inline_Stack_Item(i), PL_na));
178 Inline_Stack_Void;
180 }
181 END_OF_C_CODE
183 Discussion
185 This little program greets a group of people, such as my coworkers.
186 We use the "C" ellipsis syntax: ""..."", since the list can be of
187 any size.
188 Since there are no types or names associated with each argument, we
190 can't expect XS to handle the conversions for us. We'll need to pop
191 them off the Stack ourselves. Luckily there are two functions
192 (macros) that make this a very easy task.
193 First, we need to begin our function with a ""Inline_Stack_Vars""
195 statement. This defines a few internal variables that we need to
196 access the Stack. Now we can use ""Inline_Stack_Items"", which
197 returns an integer containing the number of arguments passed to us
198 from Perl.
199 NOTE: It is important to only use ""Inline_Stack_"" macros when
201 there is an ellipsis ("...") in the argument list, or the function
202 has a return type of void.
203 Second, we use the Inline_Stack_Item(x) function to access each
205 argument where "0 <= x < items".
206 NOTE: When using a variable length argument list, you have to
208 specify at least one argument before the ellipsis. (On my compiler,
209 anyway.) When XS does it's argument checking, it will complain if
210 you pass in less than the number of defined arguments. Therefore,
211 there is currently no way to pass an empty list when a variable
212 length list is expected.
213 See Also
215 Credits
216 Multiple Return Values
218 Problem
219 How do I return a list of values from a C function?
220 Solution
222 print map {"$_\n"} get_localtime(time);
223 use Inline C => <<'END_OF_C_CODE';
225 #include <time.h>
227 void get_localtime(SV * utc) {
229 const time_t utc_ = (time_t)SvIV(utc);
230 struct tm *ltime = localtime(&utc_);
231 Inline_Stack_Vars;
232 Inline_Stack_Reset;
234 Inline_Stack_Push(sv_2mortal(newSViv(ltime->tm_year)));
235 Inline_Stack_Push(sv_2mortal(newSViv(ltime->tm_mon)));
236 Inline_Stack_Push(sv_2mortal(newSViv(ltime->tm_mday)));
237 Inline_Stack_Push(sv_2mortal(newSViv(ltime->tm_hour)));
238 Inline_Stack_Push(sv_2mortal(newSViv(ltime->tm_min)));
239 Inline_Stack_Push(sv_2mortal(newSViv(ltime->tm_sec)));
240 Inline_Stack_Push(sv_2mortal(newSViv(ltime->tm_isdst)));
241 Inline_Stack_Done;
242 }
243 END_OF_C_CODE
244 Discussion
246 Perl is a language where it is common to return a list of values
247 from a subroutine call instead of just a single value. C is not
248 such a language. In order to accomplish this in C we need to
249 manipulate the Perl call stack by hand. Luckily, Inline provides
250 macros to make this easy.
251 This example calls the system "localtime", and returns each of the
253 parts of the time struct; much like the perl builtin "localtime()".
254 On each stack push, we are creating a new Perl integer (SVIV) and
255 mortalizing it. The sv_2mortal() call makes sure that the reference
256 count is set properly. Without it, the program would leak memory.
257 NOTE: The "#include" statement is not really needed, because Inline
259 automatically includes the Perl headers which include almost
260 all
261 standard system calls.
262 See Also
264 For more information on the Inline stack macros, see Inline::C.
265 Credits
267 Richard Anderson <starfire@zipcon.net> contributed the original
268 idea for this snippet.
269 Multiple Return Values (Another Way)
271 Problem
272 How can I pass back more than one value without using the Perl
273 Stack?
274 Solution
276 use Inline::Files;
277 use Inline 'C';
278 my ($foo, $bar);
280 change($foo, $bar);
281 print "\$foo = $foo\n";
283 print "\$bar = $bar\n";
284 __C__
286 int change(SV* var1, SV* var2) {
288 sv_setpvn(var1, "Perl Rocks!", 11);
289 sv_setpvn(var2, "Inline Rules!", 13);
290 return 1;
291 }
292 Discussion
294 Most perl function interfaces return values as a list of one or
295 more scalars. Very few like "chomp", will modify an input scalar
296 in place. On the other hand, in C you do this quite often. Values
297 are passed in by reference and modified in place by the called
298 function.
299 It turns out that we can do that with Inline as well. The secret is
301 to use a type of '"SV*"' for each argument that is to be modified.
302 This ensures passing by reference, because no typemapping is
303 needed.
304 The function can then use the Perl5 API to operate on that
306 argument. When control returns to Perl, the argument will retain
307 the value set by the C function. In this example we passed in 2
308 empty scalars and assigned values directly to them.
309 See Also
311 Credits
312 Ned Konz <ned@bike-nomad.com> brought this behavior to my
313 attention. He also pointed out that he is not the world famous
314 computer cyclist Steve Roberts ( <http://www.microship.com> ), but
315 he is close ( <http://bike-nomad.com> ). Thanks Ned.
316 Taking an array-ref as an argument
318 Problem
319 How can I take a Perl array-ref as an argument in my C function?
320 Solution
322 SV *sum(SV *array) {
323 int total = 0;
324 int numelts, i;
325 if ((!SvROK(array))
326 || (SvTYPE(SvRV(array)) != SVt_PVAV)
327 || ((numelts = av_len((AV *)SvRV(array))) < 0)
328 ) {
329 return &PL_sv_undef;
330 }
331 for (i = 0; i <= numelts; i++) {
332 total += SvIV(*av_fetch((AV *)SvRV(array), i, 0));
333 }
334 return newSViv(total);
335 }
336 Discussion
338 This example returns "undef" if given a non-ref, or a non-array-
339 ref, or a ref to an empty array. You can see how you might expand
340 this to take more than one array-ref.
341 Using Memory
343 Problem
344 How should I allocate buffers in my Inline C code?
345 Solution
347 print greeting('Ingy');
348 use Inline C => <<'END_OF_C_CODE';
350 SV* greeting(SV* sv_name) {
352 return (newSVpvf("Hello %s!\n", SvPV(sv_name, PL_na)));
353 }
354 END_OF_C_CODE
356 Discussion
358 In this example we will return the greeting to the caller, rather
359 than printing it. This would seem mighty easy, except for the fact
360 that we need to allocate a small buffer to create the greeting.
361 I would urge you to stay away from "malloc"ing your own buffer.
363 Just use Perl's built in memory management. In other words, just
364 create a new Perl string scalar. The function "newSVpv" does just
365 that. And "newSVpvf" includes "sprintf" functionality.
366 The other problem is getting rid of this new scalar. How will the
368 ref count get decremented after we pass the scalar back? Perl also
369 provides a function called "sv_2mortal". Mortal variables die when
370 the context goes out of scope. In other words, Perl will wait
371 until the new scalar gets passed back and then decrement the ref
372 count for you, thereby making it eligible for garbage collection.
373 See "perldoc perlguts".
374 In this example the "sv_2mortal" call gets done under the hood by
376 XS, because we declared the return type to be "SV*".
377 To view the generated XS code, run the command ""perl -
379 MInline=INFO,FORCE,NOCLEAN example004.pl"". This will leave the
380 build directory intact and tell you where to find it.
381 See Also
383 Credits
384 Direct Access to Perl variables
386 Problem
387 Can I write an Inline C function that can access a Perl variable
388 directly without having to pass it as an argument?
389 Solution
391 use strict;
392 use warnings;
393 use Inline C => "DATA";
394 our $mesh_data = "MESH-POINTS 0.0 0.0 0.5 0.25 1.0 0.5 1.5 0.75";
396 CalcSurfaceHeights();
397 __DATA__
399 __C__
400 #define N_MP 4
401 void CalcSurfaceHeights() {
403 double x[N_MP], y[N_MP], z;
404 int ix;
405 char *mesh_data = SvPV_nolen(get_sv("main::mesh_data", 0));
406 sscanf(mesh_data, "MESH-POINTS %lf%lf%lf%lf%lf%lf%lf%lf",
408 x, y, x+1, y+1, x+2, y+2, x+3, y+3);
409 for (ix=0; ix < N_MP; ix++) {
411 z = 0.5*( sin(x[ix]) + sin(y[ix]) );
412 printf("Surface-Height: %6.3f Mesh-Point: %6.2f, %6.2f\n",
414 z, x[ix], y[ix]);
415 }
416 }
417 Discussion
419 There are really only two points that need an explanation to
420 understand why the above code works. In the Perl section, you will
421 notice the declaration
422 our $mesh_data = "...";
424 For Perl variables to be directly accessible from Inline::C
426 functions, they must be declared as package variables. Lexical
427 variables, those declared with my, cannot be accessed this way.
428 In the C code section of the example, the following line is what
430 makes direct access to the Perl variable work;
431 char *mesh_data = SvPV_nolen(get_sv("main::mesh_data", 0))
433 Here SvPV_nolen() returns a pointer to the C string contained in
435 the scalar variable. The "_nolen" variation ignores the length of
436 the C string. Hence, the function takes only a single argument,
437 which is the SV* of the scalar variable.
438 We could have used the usual two-argument form of SvPV() and, since
440 we don't care about the string length, specified PL_na for the
441 second argument. The function call would then change to,
442 SvPV(get_sv("main::mesh_data", 0), PL_na)
444 The function get_sv() returns the SV* of a named scalar package
446 variable. It takes a C string, containing the fully qualified name
447 of the variable, as the first argument. The second argument
448 contains flag values related to data type. Since we are only
449 reading the scalar variable, in our example, a value of 0 can be
450 used.
451 See Also
453 • perldoc perlguts
454 • perldoc perlapi
456 Credits
458 The code example and description were inspired by a discussion
459 thread on the Inline mailing list (inline@perl.org).
460
462 Inline CGI
463 Problem
464 How do I use Inline securely in a CGI environment?
465 Solution
467 #!/usr/bin/perl
468 use CGI qw(:standard);
470 use Inline Config =>
471 DIRECTORY => '/usr/local/apache/Inline';
472 print
474 header,
475 start_html('Inline CGI Example'),
476 h1(JAxH('Inline')),
477 end_html;
478 use Inline C => <<END;
480 SV* JAxH(char* x) {
481 return newSVpvf("Just Another %s Hacker", x);
482 }
483 END
484 Discussion
486 The problem with running Inline code from a CGI script is that
487 Inline writes to a build area on your disk whenever it compiles
488 code. Most CGI scripts don't (and shouldn't) be able to create a
489 directory and write into it.
490 The solution is to explicitly tell Inline which directory to use
492 with the 'use Inline Config => DIRECTORY => ...' line. Then you
493 need to give write access to that directory from the web server
494 (CGI script).
495 If you see this as a security hole, then there is another option.
497 Give write access to yourself, but read-only access to the CGI
498 script. Then run the script once by hand (from the command line).
499 This will cause Inline to precompile the C code. That way the CGI
500 will only need read access to the build directory (to load in the
501 shared library from there).
502 Just remember that whenever you change the C code, you need to
504 precompile it again.
505 See Also
507 See CGI for more information on using the "CGI.pm" module.
508 Credits
510 mod_perl
512 Problem
513 How do I use Inline with mod_perl?
515 Solution
517 package Factorial;
518 use strict;
519 use Inline Config =>
520 DIRECTORY => '/usr/local/apache/Inline',
521 enable => 'UNTAINT';
522 use Inline 'C';
523 Inline->init;
524 sub handler {
526 my $r = shift;
527 $r->send_http_header('text/plain');
528 printf "%3d! = %10d\n", $_, factorial($_) for 1..100;
529 return Apache::Constants::OK;
530 }
531 1;
533 __DATA__
534 __C__
535 double factorial(double x) {
536 if (x < 2) return 1;
537 return x * factorial(x - 1)
538 }
539 Discussion
541 This is a fully functional mod_perl handler that prints out the
542 factorial values for the numbers 1 to 100. Since we are using
543 Inline under mod_perl, there are a few considerations to , um,
544 consider.
545 First, mod_perl handlers are usually run with "-T" taint detection.
547 Therefore, we need to enable the UNTAINT option. The next thing to
548 deal with is the fact that this handler will most likely be loaded
549 after Perl's compile time. Since we are using the DATA section, we
550 need to use the special "init()" call. And of course we need to
551 specify a DIRECTORY that mod_perl can compile into. See the above
552 CGI example for more info.
553 Other than that, this is a pretty straightforward mod_perl handler,
555 tuned for even more speed!
556 See Also
558 See Stas Bekman's upcoming O'Reilly book on mod_perl to which this
559 example was contributed.
560 Object Oriented Inline
562 Problem
563 How do I implement Object Oriented programming in Perl using C objects?
565 Solution
567 my $obj1 = Soldier->new('Benjamin', 'Private', 11111);
568 my $obj2 = Soldier->new('Sanders', 'Colonel', 22222);
569 my $obj3 = Soldier->new('Matt', 'Sergeant', 33333);
570 for my $obj ($obj1, $obj2, $obj3) {
572 print $obj->get_serial, ") ",
573 $obj->get_name, " is a ",
574 $obj->get_rank, "\n";
575 }
576 #---------------------------------------------------------
578 package Soldier;
580 use Inline C => <<'END';
582 /*
584 Allocate memory with Newx if it's
585 available - if it's an older perl
586 that doesn't have Newx then we
587 resort to using New.
588 */
589 #ifndef Newx
590 # define Newx(v,n,t) New(0,v,n,t)
591 #endif
592 typedef struct {
594 char* name;
595 char* rank;
596 long serial;
597 } Soldier;
598 SV* new(const char * classname, const char * name,
600 const char * rank, long serial) {
601 Soldier * soldier;
602 SV * obj;
603 SV * obj_ref;
604 Newx(soldier, 1, Soldier);
606 soldier->name = savepv(name);
607 soldier->rank = savepv(rank);
608 soldier->serial = serial;
609 obj = newSViv((IV)soldier);
611 obj_ref = newRV_noinc(obj);
612 sv_bless(obj_ref, gv_stashpv(classname, GV_ADD));
613 SvREADONLY_on(obj);
614 return obj_ref;
616 }
617 char* get_name(SV* obj) {
619 return ((Soldier*)SvIV(SvRV(obj)))->name;
620 }
621 char* get_rank(SV* obj) {
623 return ((Soldier*)SvIV(SvRV(obj)))->rank;
624 }
625 long get_serial(SV* obj) {
627 return ((Soldier*)SvIV(SvRV(obj)))->serial;
628 }
629 void DESTROY(SV* obj) {
631 Soldier* soldier = (Soldier*)SvIV(SvRV(obj));
632 Safefree(soldier->name);
633 Safefree(soldier->rank);
634 Safefree(soldier);
635 }
636 END
638 Discussion
640 Damian Conway has given us myriad ways of implementing OOP in Perl.
642 This is one he might not have thought of.
643 The interesting thing about this example is that it uses Perl for all
645 the OO bindings while using C for the attributes and methods.
646 If you examine the Perl code everything looks exactly like a regular OO
648 example. There is a "new" method and several accessor methods. The
649 familiar 'arrow syntax' is used to invoke them.
650 In the class definition (second part) the Perl "package" statement is
652 used to name the object class or namespace. But that's where the
653 similarities end Inline takes over.
654 The idea is that we call a C subroutine called "new()" which returns a
656 blessed scalar. The scalar contains a readonly integer which is a C
657 pointer to a Soldier struct. This is our object.
658 The "new()" function needs to malloc the memory for the struct and then
660 copy the initial values into it using "savepv()". This also allocates
661 more memory (which we have to keep track of).
662 The accessor methods are pretty straightforward. They return the
664 current value of their attribute.
665 The last method "DESTROY()" is called automatically by Perl whenever an
667 object goes out of scope. This is where we can free all the memory used
668 by the object.
669 That's it. It's a very simplistic example. It doesn't show off any
671 advanced OO features, but it is pretty cool to see how easy the
672 implementation can be. The important Perl call is "newSVrv()" which
673 creates a blessed scalar.
674 See Also
676 Read "Object Oriented Perl" by Damian Conway, for more useful ways of
678 doing OOP in Perl.
679 You can learn more Perl calls in perlapi. If you don't have Perl 5.6.0
681 or higher, visit <http://www.perldoc.com/perl5.6/pod/perlapi.html>
682
684 Exposing Shared Libraries
685 Problem
686 You have this great C library and you want to be able to access
687 parts of it with Perl.
688 Solution
690 print get('http://www.axkit.org');
691 use Inline C => Config =>
693 LIBS => '-lghttp';
694 use Inline C => <<'END_OF_C_CODE';
695 #include <ghttp.h>
697 char *get(SV* uri) {
699 SV* buffer;
700 ghttp_request* request;
701 buffer = NEWSV(0,0);
703 request = ghttp_request_new();
704 ghttp_set_uri(request, SvPV(uri, PL_na));
705 ghttp_set_header(request, http_hdr_Connection, "close");
707 ghttp_prepare(request);
709 ghttp_process(request);
710 sv_catpv(buffer, ghttp_get_body(request));
712 ghttp_request_destroy(request);
714 return SvPV(buffer, PL_na);
716 }
717 END_OF_C_CODE
719 Discussion
721 This example fetches and prints the HTML from
722 <http://www.axkit.org> Itrequires the GNOME http libraries.
723 <http://www.gnome.org>
724 One of the most common questions I get is "How can I use Inline to
726 make use of some shared library?". Although it has always been
727 possible to do so, the configuration was ugly, and there were no
728 specific examples.
729 With version 0.30 and higher, you can specify the use of shared
731 libraries easily with something like this:
732 use Inline C => Config => LIBS => '-lghttp';
734 use Inline C => "code ...";
735 or
737 use Inline C => "code ...", LIBS => '-lghttp';
739 To specify a specific library path, use:
741 use Inline C => "code ...", LIBS => '-L/your/lib/path -lyourlib';
743 To specify an include path use:
745 use Inline C => "code ...",
747 LIBS => '-lghttp',
748 INC => '-I/your/inc/path';
749 See Also
751 The "LIBS" and "INC" configuration options are formatted and passed
752 into MakeMaker. For more info see ExtUtils::MakeMaker. For more
753 options see Inline::C.
754 Credits
756 This code was written by Matt Sergeant <matt@sergeant.org>, author
757 of many CPAN modules. The configuration syntax has been modified
758 for use with Inline v0.30.
759 Automatic Function Wrappers
761 Problem
762 You have some functions in a C library that you want to access from
763 Perl exactly as you would from C.
764 Solution
766 The error function "erf()" is probably defined in your standard
767 math library. Annoyingly, Perl does not let you access it. To
768 print out a small table of its values, just say:
769 perl -le 'use Inline C => q{ double erf(double); }, enable => "autowrap"; print "$_ @{[erf($_)]}" for (0..10)'
771 The excellent "Term::ReadLine::Gnu" implements Term::ReadLine using
773 the GNU ReadLine library. Here is an easy way to access just
774 "readline()" from that library:
775 package MyTerm;
777 use Inline C => Config =>
779 enable => autowrap =>
780 LIBS => "-lreadline -lncurses -lterminfo -ltermcap ";
781 use Inline C => q{ char * readline(char *); };
782 package main;
784 my $x = MyTerm::readline("xyz: ");
785 Note however that it fails to "free()" the memory returned by
787 readline, and that "Term::ReadLine::Gnu" offers a much richer
788 interface.
789 Discussion
791 We access existing functions by merely showing Inline their
792 declarations, rather than a full definition. Of course the function
793 declared must exist, either in a library already linked to Perl or
794 in a library specified using the "LIBS" option.
795 The first example wraps a function from the standard math library,
797 so Inline requires no additional "LIBS" directive. The second uses
798 the Config option to specify the libraries that contain the actual
799 compiled C code.
800 This behavior is always disabled by default. You must enable the
802 "autowrap" option to make it work.
803 See Also
805 • "readline"
806 • "Term::ReadLine::Gnu"
808 Credits
810 GNU ReadLine was written by Brian Fox <bfox@ai.mit.edu> and Chet
811 Ramey <chet@ins.cwru.edu>. Term::ReadLine::Gnu was written by Hiroo
812 Hayashi <hiroo.hayashi@computer.org>. Both are far richer than the
813 slim interface given here!
814 The idea of producing wrapper code given only a function
816 declaration is taken from Swig by David M. Beazley
817 <beazley@cs.uchicago.edu>.
818 Ingy's inline editorial insight:
820 This entire entry was contributed by Ariel Scolnicov
822 <ariels@compugen.co.il>. Ariel also first suggested the idea for
823 Inline to support function declaration processing.
824 Replacing h2xs
826 Problem
827 You have a complete C library that you want to access from Perl
828 exactly as you would from C.
829 Solution
831 Just say:
832 use IO::All;
834 use Inline C => sub { io('allheaders.h')->all =~ s/LEPT_DLL extern//gr },
835 enable => "autowrap",
836 libs => '-lleptonica';
837 Discussion
839 In principle, you can use h2xs to wrap a C library into an XS
840 module. One problem with this is that the C parser code is a little
841 out of date. Also, since it works by generating a number of files,
842 maintaining it when the C library changes is a certain amount of
843 work. Using Inline to do the work is much easier.
844 If the header file needs some processing, like removing some text
846 that a full C compiler can deal with, but the Inline::C parser
847 cannot, as in the example above? Well, Perl is good at text-
848 processing.
849 Complex Data
851 Problem
852 How do I deal with complex data types like hashes in Inline C?
854 Solution
856 use Inline C => <<'END_OF_C_CODE';
857 void dump_hash(SV* hash_ref) {
859 HV* hash;
860 HE* hash_entry;
861 int num_keys, i;
862 SV* sv_key;
863 SV* sv_val;
864 if (! SvROK(hash_ref))
866 croak("hash_ref is not a reference");
867 hash = (HV*)SvRV(hash_ref);
869 num_keys = hv_iterinit(hash);
870 for (i = 0; i < num_keys; i++) {
871 hash_entry = hv_iternext(hash);
872 sv_key = hv_iterkeysv(hash_entry);
873 sv_val = hv_iterval(hash, hash_entry);
874 printf("%s => %s\n", SvPV(sv_key, PL_na), SvPV(sv_val, PL_na));
875 }
876 return;
877 }
878 END_OF_C_CODE
880 my %hash = (
882 Author => "Ingy döt Net",
883 Nickname => "INGY",
884 Module => "Inline.pm",
885 Version => "0.30",
886 Language => "C",
887 );
888 dump_hash(\%hash);
890 Discussion
892 The world is not made of scalars alone, although they are
893 definitely the easiest creatures to deal with, when doing Inline
894 stuff. Sometimes we need to deal with arrays, hashes, and code
895 references, among other things.
896 Since Perl subroutine calls only pass scalars as arguments, we'll
898 need to use the argument type "SV*" and pass references to more
899 complex types.
900 The above program dumps the key/value pairs of a hash. To figure it
902 out, just curl up with perlapi for a couple hours. Actually, its
903 fairly straight forward once you are familiar with the calls.
904 Note the "croak" function call. This is the proper way to die from
906 your C extensions.
907 See Also
909 See perlapi for information about the Perl5 internal API.
910 Credits
912 Hash of Lists
914 Problem
915 How do I create a Hash of Lists from C?
917 Solution
919 use Inline 'C';
920 use Data::Dumper;
921 $hash_ref = load_data("./cartoon.txt");
923 print Dumper $hash_ref;
924 __END__
926 __C__
927 static int next_word(char**, char*);
929 SV* load_data(char* file_name) {
931 char buffer[100], word[100], * pos;
932 AV* array;
933 HV* hash = newHV();
934 FILE* fh = fopen(file_name, "r");
935 while (fgets(pos = buffer, sizeof(buffer), fh)) {
937 if (next_word(&pos, word)) {
938 array = newAV();
939 hv_store(hash, word, strlen(word),
940 newRV_noinc((SV*)array), 0);
941 while (next_word(&pos, word))
942 av_push(array, newSVpvf("%s", word));
943 }
944 }
945 fclose(fh);
946 return newRV_noinc((SV*) hash);
947 }
948 static int next_word(char** text_ptr, char* word) {
950 char* text = *text_ptr;
951 while(*text != '\0' &&
952 *text <= ' ')
953 text++;
954 if (*text <= ' ')
955 return 0;
956 while(*text != '\0' &&
957 *text > ' ') {
958 *word++ = *text++;
959 }
960 *word = '\0';
961 *text_ptr = text;
962 return 1;
963 }
964 Discussion
966 This is one of the larger recipes. But when you consider the number
967 of calories it has, it's not so bad. The function "load_data" takes
968 the name of a file as it's input. The file "cartoon.text" might
969 look like:
970 flintstones fred barney
972 jetsons george jane elroy
973 simpsons homer marge bart
974 The function will read the file, parsing each line into words. Then
976 it will create a new hash, whereby the first word in a line becomes
977 a hash key and the remaining words are put into an array whose
978 reference becomes the hash value. The output looks like this:
979 $VAR1 = {
981 'flintstones' => [
982 'fred',
983 'barney'
984 ],
985 'simpsons' => [
986 'homer',
987 'marge',
988 'bart'
989 ],
990 'jetsons' => [
991 'george',
992 'jane',
993 'elroy'
994 ]
995 };
996 See Also
998 See perlapi for information about the Perl5 internal API.
999 Credits
1001 Al Danial <alnd@pacbell.net> requested a solution to this on
1002 comp.lang.perl.misc. He borrowed the idea from the "Hash of Lists"
1003 example in the Camel book.
1004
1006 Win32
1007 Problem
1008 How do I access Win32 DLL-s using Inline?
1009 Solution
1011 use Inline C => DATA =>
1012 LIBS => '-luser32';
1013 $text = "@ARGV" || 'Inline.pm works with MSWin32. Scary...';
1015 WinBox('Inline Text Box', $text);
1017 __END__
1019 __C__
1020 #include <windows.h>
1022 int WinBox(char* Caption, char* Text) {
1024 return MessageBoxA(0, Text, Caption, 0);
1025 }
1026 Discussion
1028 This example runs on MS Windows. It makes a text box appear on the
1029 screen which contains a message of your choice.
1030 The important thing is that its proof that you can use Inline to
1032 interact with Windows DLL-s. Very scary indeed. 8-o
1033 To use Inline on Windows with ActivePerl (
1035 <http://www.ActiveState.com> )you'll need MS Visual Studio. You can
1036 also use the Cygwin environment,available at
1037 <http://www.cygwin.com> .
1038 See Also
1040 See Inline-Support for more info on MSWin32 programming with
1041 Inline.
1042 Credits
1044 This example was adapted from some sample code written by Garrett
1045 Goebel <garrett@scriptpro.com>
1046 Embedding Perl in C
1048 Problem
1049 How do I use Perl from a regular C program?
1050 Solution
1052 #!/usr/bin/cpr
1053 int main(void) {
1055 printf("Using Perl version %s from a C program!\n\n",
1056 CPR_eval("use Config; $Config{version};"));
1057 CPR_eval("use Data::Dumper;");
1059 CPR_eval("print Dumper \\%INC;");
1060 return 0;
1062 }
1063 Discussion
1065 By using CPR. (C Perl Run)
1066 This example uses another Inline module, "Inline::CPR", available
1068 separately on CPAN. When you install this module it also installs a
1069 binary interpreter called "/usr/bin/cpr". (The path may be
1070 different on your system)
1071 When you feed a C program to the CPR interpreter, it automatically
1073 compiles and runs your code using Inline. This gives you full
1074 access to the Perl internals. CPR also provides a set of easy to
1075 use C macros for calling Perl internals.
1076 This means that you can effectively "run" C source code by putting
1078 a CPR hashbang as the first line of your C program.
1079 See Also
1081 See Inline::CPR for more information on using CPR.
1082 "Inline::CPR" can be obtained from
1084 <http://search.cpan.org/search?dist=Inline-CPR>
1085 Credits
1087 Randal Schwartz <merlyn@stonehenge.com>, Randolph Bentson
1088 <bentson@grieg.holmsjoen.com>, Richard Anderson
1089 <starfire@zipcon.net>, and Tim Maher <tim@consultix-inc.com> helped
1090 me figure out how to write a program that would work as a hashbang.
1091
1093 As of version 0.30, Inline has the ability to work in cooperation with
1094 other modules that want to expose a C API of their own. The general
1095 syntax for doing this is:
1096 use Inline with => 'Module';
1098 use Inline C => ... ;
1099 This tells "Module" to pass configuration options to Inline. Options
1101 like typemaps, include paths, and external libraries, are all resolved
1102 automatically so you can just concentrate on writing the functions.
1103 Event handling with Event.pm
1105 Problem
1106 You need to write a C callback for the "Event.pm" module. Can this
1107 be done more easily with Inline?
1108 Solution
1110 use Inline with => 'Event';
1111 Event->timer(desc => 'Timer #1',
1113 interval => 2,
1114 cb => \&my_callback,
1115 );
1116 Event->timer(desc => 'Timer #2',
1118 interval => 3,
1119 cb => \&my_callback,
1120 );
1121 print "Starting...\n";
1123 Event::loop;
1124 use Inline C => <<'END';
1126 void my_callback(pe_event* event) {
1127 pe_timer * watcher = event->up;
1128 printf("%s\n\tEvent priority = %d\n\tWatcher priority = %d\n\n",
1130 SvPVX(watcher->base.desc),
1131 event->prio,
1132 watcher->base.prio
1133 );
1134 }
1135 END
1136 Discussion
1138 The first line tells Inline to load the "Event.pm" module. Inline
1139 then queries "Event" for configuration information. It gets the
1140 name and location of Event's header files, typemaps and shared
1141 objects. The parameters that "Event" returns look like:
1142 INC => "-I $path/Event",
1144 TYPEMAPS => "$path/Event/typemap",
1145 MYEXTLIB => "$path/auto/Event/Event.$so",
1146 AUTO_INCLUDE => '#include "EventAPI.h"',
1147 BOOT => 'I_EVENT_API("Inline");',
1148 Doing all of this automatically allows you, the programmer, to
1150 simply write a function that receives a pointer of type
1151 'pe_event*'. This gives you access to the "Event" structure that
1152 was passed to you.
1153 In this example, I simply print values out of the structure. The
1155 Perl code defines 2 timer events which each invoke the same
1156 callback. The first one, every two seconds, and the second one,
1157 every three seconds.
1158 As of this writing, "Event.pm" is the only CPAN module that works
1160 in cooperation with Inline.
1161 See Also
1163 Read the "Event.pm" documentation for more information. It contains
1164 a tutorial showing several examples of using Inline with "Event".
1165 Credits
1167 Jochen Stenzel <perl@jochen-stenzel.de> originally came up with the
1168 idea of mixing Inline and "Event". He also authored the "Event"
1169 tutorial.
1170 Joshua Pritikin <joshua.pritikin@db.com> is the author of
1172 "Event.pm".
1173
1175 Calling C from both Perl and C
1176 Problem
1177 I'd like to be able to call the same C function from both Perl and
1178 C. Also I like to define a C function that doesn't get bound to
1179 Perl. How do I do that?
1180 Solution
1182 print "9 + 5 = ", add(9, 5), "\n";
1183 print "SQRT(9^2 + 5^2) = ", pyth(9, 5), "\n";
1184 print "9 * 5 = ", mult(9, 5), "\n";
1185 use Inline C => <<'END_C';
1187 int add(int x, int y) {
1188 return x + y;
1189 }
1190 static int mult(int x, int y) {
1191 return x * y;
1192 }
1193 double pyth(int x, int y) {
1194 return sqrt(add(mult(x, x), mult(y, y)));
1195 }
1196 END_C
1197 Discussion
1199 The program produces:
1200 9 + 5 = 14
1202 SQRT(9^2 + 5^2) = 10.295630140987
1203 Can't locate auto/main/mult.al in @INC ...
1204 Every Inline function that is bound to Perl is also callable by C.
1206 You don't have to do anything special. Inline arranges it so that
1207 all the typemap code gets done by XS and is out of sight. By the
1208 time the C function receives control, everything has been converted
1209 from Perl to C.
1210 Of course if your function manipulates the Perl Stack, you probably
1212 don't want to call it from C (unless you really know what you're
1213 doing).
1214 If you declare a function as "static", Inline won't bind it to
1216 Perl. That's why we were able to call "mult()" from C but the call
1217 failed from Perl.
1218 Calling Perl from C
1220 Problem
1221 So now that I can call C from Perl, how do I call a Perl subroutine
1222 from an Inline C function.
1223 Solution
1225 use Inline 'C';
1226 for(1..5) {
1228 c_func_1('This is the first line');
1229 c_func_2('This is the second line');
1230 print "\n";
1231 }
1232 sub perl_sub_1 {
1234 print map "$_\n", @_;
1235 }
1236 __DATA__
1238 __C__
1239 void c_func_2(SV* text) {
1241 dSP;
1242 ENTER;
1244 SAVETMPS;
1245 XPUSHs(sv_2mortal(newSVpvf("Plus an extra line")));
1247 PUTBACK;
1248 call_pv("perl_sub_1", G_DISCARD);
1250 FREETMPS;
1252 LEAVE;
1253 }
1254 void c_func_1(SV* text) {
1256 c_func_2(text);
1257 }
1258 Discussion
1260 This demo previously made use of Inline Stack macros only - but
1261 that's not the correct way to do it. Instead, base the callbacks on
1262 the perlcall documentation (as we're now doing).
1263 Actually, this program demonstrates calling a C function which
1265 calls another C function which in turn calls a Perl subroutine.
1266 The nice thing about Inline C functions is that you can call them
1268 from both Perl-space and C-space. That's because Inline creates a
1269 wrapper function around each C function. When you use Perl to call
1270 C you're actually calling that function's wrapper. The wrapper
1271 handles typemapping and Stack management, and then calls your C
1272 function.
1273 The first time we call "c_func_1" which calls "c_func_2". The
1275 second time we call "c_func_2" directly. "c_func_2" calls the Perl
1276 subroutine ("perl_sub_1") using the internal "perl_call_pv"
1277 function. It has to put arguments on the stack by hand. Since there
1278 is already one argument on the stack when we enter the function,
1279 the "XPUSHs" ( which is equivalent to an "Inline_Stack_Push" ) adds
1280 a second argument.
1281 We iterate through a 'for' loop 5 times just to demonstrate that
1283 things still work correctly when we do that. (This was where the
1284 previous rendition, making use solely of Inline Stack macros, fell
1285 down.)
1286 See Also
1288 See Inline::C for more information about Stack macros.
1289 See perlapi for more information about the Perl5 internal API.
1291 Evaling C
1293 Problem
1294 I've totally lost my marbles and I want to generate C code at run
1295 time, and "eval" it into Perl. How do I do this?
1296 Solution
1298 use Inline;
1299 use Code::Generator;
1300 my $c_code = generate('foo_function');
1302 Inline->bind(C => $c_code);
1304 foo_function(1, 2, 3);
1306 Discussion
1308 I can't think of a real life application where you would want to
1309 generate C code on the fly, but at least I know how I would do it.
1310 :)
1311 The "bind()" function of Inline let's you bind (compileloadexecute)
1313 C functions at run time. It takes all of the same arguments as "use
1314 Inline C => ...".
1315 The nice thing is that once a particular snippet is compiled, it
1317 remains cached so that it doesn't need to be compiled again. I can
1318 imagine that someday a mad scientist will dream up a self
1319 generating modeling system that would run faster and faster over
1320 time.
1321 If you know such a person, have them drop me a line.
1323 Providing a pure perl alternative
1325 Problem
1326 I want to write a script that will use a C subroutine if Inline::C
1327 is installed, but will otherwise use an equivalent pure perl
1328 subroutine if Inline::C is not already installed. How do I do this?
1329 Solution
1331 use strict;
1332 use warnings;
1333 eval {
1335 require Inline;
1336 Inline->import (C => Config =>
1337 BUILD_NOISY => 1);
1338 Inline->import (C =><<'EOC');
1339 int foo() {
1341 warn("Using Inline\n");
1342 return 42;
1343 }
1344 EOC
1346 };
1347 if ($@) {
1349 *foo =\&bar;
1350 }
1351 sub bar {
1353 warn("Using Pure Perl Implementation\n");
1354 return 42;
1355 }
1356 my $x = foo();
1358 print "$x\n";
1359 Discussion
1361 If Inline::C is installed and functioning properly, the C sub foo
1362 is called by the perl code. Otherwise, $@ gets set, and the
1363 equivalent pure perl function bar is instead called.
1364 Note, too, that the pure perl sub bar can still be explicitly
1366 called even if Inline::C is available.
1367 Accessing Fortran subs using Inline::C
1369 Problem
1370 I've been given a neat little sub written in fortran that takes, as
1371 its args, two integers and returns their product. And I would like
1372 to use that sub as is from Inline::C. By way of example, let's say
1373 that the fortran source file is named 'prod.f', and that it looks
1374 like this:
1375 integer function sqarea(r,s)
1377 integer r, s
1378 sqarea = r*s
1379 return
1380 end
1381 Solution
1383 We can't access that code directly, but we can compile it into a
1384 library which we can then access from Inline::C. Using gcc we could
1385 run:
1386 gfortran -c prod.f -o prod.o
1388 ar cru libprod.a prod.o
1389 The function is then accessible as follows:
1391 use warnings;
1393 use Inline C => Config =>
1395 LIBS => '-L/full/path/to/libprod_location -lprod -lgfortran';
1396 use Inline C => <<' EOC';
1398 int wrap_sqarea(int a, int b) {
1400 return sqarea_(&a, &b);
1401 }
1402 EOC
1404 $x = 15;
1406 $y = $x + 3;
1407 $ret = wrap_sqarea($x, $y);
1408 print "Product of $x and $y is $ret\n";
1409 Discussion
1411 Note firstly that, although the function is specified as 'sqarea'
1412 in the source file, gfortran appends an underscore to the name when
1413 the source is compiled. (I don't know if all fortran compilers do
1414 this.) Therefore Inline::C needs to call the function as 'sqarea_'.
1415 Secondly, because fortran subs pass args by reference, we need to
1417 pass the addresses of the two integer args to sqarea() when we call
1418 it from our Inline::C sub.
1419 If using g77 instead of gfortran, the only necessary change is that
1421 we specify '-lg2c' instead of '-lgfortran' in our 'LIBS' setting.
1422
1424 For generic information about Inline, see Inline.
1425 For information about using Inline with C see Inline::C.
1427 For information on supported languages and platforms see Inline-
1429 Support.
1430 For information on writing your own Inline language support module, see
1432 Inline-API.
1433 Inline's mailing list is inline@perl.org
1435 To subscribe, send email to inline-subscribe@perl.org
1437
1439 Ingy döt Net <ingy@cpan.org>
1440 Sisyphus <sisyphus@cpan.org>
1442
1444 Copyright 2000-2019. Ingy döt Net.
1445 Copyright 2008, 2010-2014. Sisyphus.
1447 This program is free software; you can redistribute it and/or modify it
1449 under the same terms as Perl itself.
1450 See <http://www.perl.com/perl/misc/Artistic.html>
1452perl v5.34.0 2021-07-22 Inline::C::Cookbook(3)