3 perlembed - how to embed perl in your C program
13 =item B<Use C from Perl?>
15 Read L<perlcall> and L<perlxs>.
17 =item B<Use a UNIX program from Perl?>
19 Read about backquotes and about C<system> and C<exec> in L<perlfunc>.
21 =item B<Use Perl from Perl?>
23 Read about C<do> and C<eval> in L<perlfunc/do> and L<perlfunc/eval> and C<use>
24 and C<require> in L<perlmod> and L<perlfunc/require>, L<perlfunc/use>.
26 =item B<Use C from C?>
30 =item B<Use Perl from C?>
38 L<Compiling your C program>
40 There's one example in each of the six sections:
42 L<Adding a Perl interpreter to your C program>
44 L<Calling a Perl subroutine from your C program>
46 L<Evaluating a Perl statement from your C program>
48 L<Performing Perl pattern matches and substitutions from your C program>
50 L<Fiddling with the Perl stack from your C program>
52 L<Using Perl modules, which themselves use C libraries, from your C program>
54 This documentation is UNIX specific.
56 =head2 Compiling your C program
58 Every C program that uses Perl must link in the I<perl library>.
60 What's that, you ask? Perl is itself written in C; the perl library
61 is the collection of compiled C programs that were used to create your
62 perl executable (I</usr/bin/perl> or equivalent). (Corollary: you
63 can't use Perl from your C program unless Perl has been compiled on
64 your machine, or installed properly--that's why you shouldn't blithely
65 copy Perl executables from machine to machine without also copying the
68 Your C program will--usually--allocate, "run", and deallocate a
69 I<PerlInterpreter> object, which is defined in the perl library.
71 If your copy of Perl is recent enough to contain this documentation
72 (5.002 or later), then the perl library (and I<EXTERN.h> and
73 I<perl.h>, which you'll also need) will
74 reside in a directory resembling this:
76 /usr/local/lib/perl5/your_architecture_here/CORE
80 /usr/local/lib/perl5/CORE
82 or maybe something like
86 Execute this statement for a hint about where to find CORE:
88 perl -MConfig -e 'print $Config{archlib}'
90 Here's how you might compile the example in the next section,
91 L<Adding a Perl interpreter to your C program>,
92 on a DEC Alpha running the OSF operating system:
94 % cc -o interp interp.c -L/usr/local/lib/perl5/alpha-dec_osf/CORE
95 -I/usr/local/lib/perl5/alpha-dec_osf/CORE -lperl -lm
97 You'll have to choose the appropriate compiler (I<cc>, I<gcc>, et al.) and
98 library directory (I</usr/local/lib/...>) for your machine. If your
99 compiler complains that certain functions are undefined, or that it
100 can't locate I<-lperl>, then you need to change the path following the
101 -L. If it complains that it can't find I<EXTERN.h> or I<perl.h>, you need
102 to change the path following the -I.
104 You may have to add extra libraries as well. Which ones?
105 Perhaps those printed by
107 perl -MConfig -e 'print $Config{libs}'
109 We strongly recommend you use the B<ExtUtils::Embed> module to determine
110 all of this information for you:
112 % cc -o interp interp.c `perl -MExtUtils::Embed -e ccopts -e ldopts`
115 If the B<ExtUtils::Embed> module is not part of your perl kit's
116 distribution you can retrieve it from:
117 http://www.perl.com/cgi-bin/cpan_mod?module=ExtUtils::Embed.
120 =head2 Adding a Perl interpreter to your C program
122 In a sense, perl (the C program) is a good example of embedding Perl
123 (the language), so I'll demonstrate embedding with I<miniperlmain.c>,
124 from the source distribution. Here's a bastardized, non-portable version of
125 I<miniperlmain.c> containing the essentials of embedding:
128 #include <EXTERN.h> /* from the Perl distribution */
129 #include <perl.h> /* from the Perl distribution */
131 static PerlInterpreter *my_perl; /*** The Perl interpreter ***/
133 int main(int argc, char **argv, char **env)
135 my_perl = perl_alloc();
136 perl_construct(my_perl);
137 perl_parse(my_perl, NULL, argc, argv, (char **)NULL);
139 perl_destruct(my_perl);
143 Note that we do not use the C<env> pointer here or in any of the
145 Normally handed to C<perl_parse> as it's final argument,
146 we hand it a B<NULL> instead, in which case the current environment
149 Now compile this program (I'll call it I<interp.c>) into an executable:
151 % cc -o interp interp.c `perl -MExtUtils::Embed -e ccopts -e ldopts`
153 After a successful compilation, you'll be able to use I<interp> just
157 print "Pretty Good Perl \n";
158 print "10890 - 9801 is ", 10890 - 9801;
165 % interp -e 'printf("%x", 3735928559)'
168 You can also read and execute Perl statements from a file while in the
169 midst of your C program, by placing the filename in I<argv[1]> before
170 calling I<perl_run()>.
172 =head2 Calling a Perl subroutine from your C program
174 To call individual Perl subroutines, you'll need to remove the call to
175 I<perl_run()> and replace it with a call to I<perl_call_argv()>.
177 That's shown below, in a program I'll call I<showtime.c>.
183 static PerlInterpreter *my_perl;
185 int main(int argc, char **argv, char **env)
187 my_perl = perl_alloc();
188 perl_construct(my_perl);
190 perl_parse(my_perl, NULL, argc, argv, NULL);
192 /*** This replaces perl_run() ***/
193 perl_call_argv("showtime", G_DISCARD | G_NOARGS, argv);
194 perl_destruct(my_perl);
198 where I<showtime> is a Perl subroutine that takes no arguments (that's the
199 I<G_NOARGS>) and for which I'll ignore the return value (that's the
200 I<G_DISCARD>). Those flags, and others, are discussed in L<perlcall>.
202 I'll define the I<showtime> subroutine in a file called I<showtime.pl>:
204 print "I shan't be printed.";
210 Simple enough. Now compile and run:
212 % cc -o showtime showtime.c `perl -MExtUtils::Embed -e ccopts -e ldopts`
214 % showtime showtime.pl
217 yielding the number of seconds that elapsed between January 1, 1970
218 (the beginning of the UNIX epoch), and the moment I began writing this
221 If you want to pass some arguments to the Perl subroutine, or
222 you want to access the return value, you'll need to manipulate the
223 Perl stack, demonstrated in the last section of this document:
224 L<Fiddling with the Perl stack from your C program>
226 =head2 Evaluating a Perl statement from your C program
228 NOTE: This section, and the next, employ some very brittle techniques
229 for evaluating strings of Perl code. Perl 5.002 contains some nifty
230 features that enable A Better Way (such as with L<perlguts/perl_eval_sv>).
231 Look for updates to this document soon.
233 One way to evaluate a Perl string is to define a function (we'll call
234 ours I<perl_eval()>) that wraps around Perl's L<perlfunc/eval>.
236 Arguably, this is the only routine you'll ever need to execute
237 snippets of Perl code from within your C program. Your string can be
238 as long as you wish; it can contain multiple statements; it can
239 use L<perlfunc/require> or L<perlfunc/do> to include external Perl
242 Our I<perl_eval()> lets us evaluate individual Perl strings, and then
243 extract variables for coercion into C types. The following program,
244 I<string.c>, executes three Perl strings, extracting an C<int> from
245 the first, a C<float> from the second, and a C<char *> from the third.
251 static PerlInterpreter *my_perl;
253 int perl_eval(char *string)
258 perl_call_argv("_eval_", 0, argv);
261 main (int argc, char **argv, char **env)
263 char *embedding[] = { "", "-e", "sub _eval_ { eval $_[0] }" };
266 my_perl = perl_alloc();
267 perl_construct( my_perl );
269 perl_parse(my_perl, NULL, 3, embedding, NULL);
271 /** Treat $a as an integer **/
272 perl_eval("$a = 3; $a **= 2");
273 printf("a = %d\n", SvIV(perl_get_sv("a", FALSE)));
275 /** Treat $a as a float **/
276 perl_eval("$a = 3.14; $a **= 2");
277 printf("a = %f\n", SvNV(perl_get_sv("a", FALSE)));
279 /** Treat $a as a string **/
280 perl_eval("$a = 'rekcaH lreP rehtonA tsuJ'; $a = reverse($a); ");
281 printf("a = %s\n", SvPV(perl_get_sv("a", FALSE), length));
283 perl_destruct(my_perl);
287 All of those strange functions with I<sv> in their names help convert Perl scalars to C types. They're described in L<perlguts>.
289 If you compile and run I<string.c>, you'll see the results of using
290 I<SvIV()> to create an C<int>, I<SvNV()> to create a C<float>, and
291 I<SvPV()> to create a string:
295 a = Just Another Perl Hacker
298 =head2 Performing Perl pattern matches and substitutions from your C program
300 Our I<perl_eval()> lets us evaluate strings of Perl code, so we can
301 define some functions that use it to "specialize" in matches and
302 substitutions: I<match()>, I<substitute()>, and I<matches()>.
304 char match(char *string, char *pattern);
306 Given a string and a pattern (e.g. "m/clasp/" or "/\b\w*\b/", which in
307 your program might be represented as C<"/\\b\\w*\\b/">),
308 returns 1 if the string matches the pattern and 0 otherwise.
311 int substitute(char *string[], char *pattern);
313 Given a pointer to a string and an "=~" operation (e.g. "s/bob/robert/g" or
314 "tr[A-Z][a-z]"), modifies the string according to the operation,
315 returning the number of substitutions made.
317 int matches(char *string, char *pattern, char **matches[]);
319 Given a string, a pattern, and a pointer to an empty array of strings,
320 evaluates C<$string =~ $pattern> in an array context, and fills in
321 I<matches> with the array elements (allocating memory as it does so),
322 returning the number of matches found.
324 Here's a sample program, I<match.c>, that uses all three (long lines have
330 static PerlInterpreter *my_perl;
331 int perl_eval(char *string)
336 perl_call_argv("_eval_", 0, argv);
338 /** match(string, pattern)
340 ** Used for matches in a scalar context.
342 ** Returns 1 if the match was successful; 0 otherwise.
344 char match(char *string, char *pattern)
347 command = malloc(sizeof(char) * strlen(string) + strlen(pattern) + 37);
348 sprintf(command, "$string = '%s'; $return = $string =~ %s",
352 return SvIV(perl_get_sv("return", FALSE));
354 /** substitute(string, pattern)
356 ** Used for =~ operations that modify their left-hand side (s/// and tr///)
358 ** Returns the number of successful matches, and
359 ** modifies the input string if there were any.
361 int substitute(char *string[], char *pattern)
365 command = malloc(sizeof(char) * strlen(*string) + strlen(pattern) + 35);
366 sprintf(command, "$string = '%s'; $ret = ($string =~ %s)",
370 *string = SvPV(perl_get_sv("string", FALSE), length);
371 return SvIV(perl_get_sv("ret", FALSE));
373 /** matches(string, pattern, matches)
375 ** Used for matches in an array context.
377 ** Returns the number of matches,
378 ** and fills in **matches with the matching substrings (allocates memory!)
380 int matches(char *string, char *pattern, char **match_list[])
388 command = malloc(sizeof(char) * strlen(string) + strlen(pattern) + 38);
389 sprintf(command, "$string = '%s'; @array = ($string =~ %s)",
393 array = perl_get_av("array", FALSE);
394 num_matches = av_len(array) + 1; /** assume $[ is 0 **/
395 *match_list = (char **) malloc(sizeof(char *) * num_matches);
396 for (i = 0; i <= num_matches; i++) {
397 current_match = av_shift(array);
398 (*match_list)[i] = SvPV(current_match, length);
402 main (int argc, char **argv, char **env)
404 char *embedding[] = { "", "-e", "sub _eval_ { eval $_[0] }" };
405 char *text, **match_list;
408 my_perl = perl_alloc();
409 perl_construct( my_perl );
410 perl_parse(my_perl, NULL, 3, embedding, NULL);
411 text = (char *) malloc(sizeof(char) * 486); /** A long string follows! **/
412 sprintf(text, "%s", "When he is at a convenience store and the bill \
413 comes to some amount like 76 cents, Maynard is aware that there is \
414 something he *should* do, something that will enable him to get back \
415 a quarter, but he has no idea *what*. He fumbles through his red \
416 squeezey changepurse and gives the boy three extra pennies with his \
417 dollar, hoping that he might luck into the correct amount. The boy \
418 gives him back two of his own pennies and then the big shiny quarter \
419 that is his prize. -RICHH");
420 if (match(text, "m/quarter/")) /** Does text contain 'quarter'? **/
421 printf("match: Text contains the word 'quarter'.\n\n");
423 printf("match: Text doesn't contain the word 'quarter'.\n\n");
424 if (match(text, "m/eighth/")) /** Does text contain 'eighth'? **/
425 printf("match: Text contains the word 'eighth'.\n\n");
427 printf("match: Text doesn't contain the word 'eighth'.\n\n");
428 /** Match all occurrences of /wi../ **/
429 num_matches = matches(text, "m/(wi..)/g", &match_list);
430 printf("matches: m/(wi..)/g found %d matches...\n", num_matches);
431 for (i = 0; i < num_matches; i++)
432 printf("match: %s\n", match_list[i]);
434 for (i = 0; i < num_matches; i++) {
438 /** Remove all vowels from text **/
439 num_matches = substitute(&text, "s/[aeiou]//gi");
441 printf("substitute: s/[aeiou]//gi...%d substitutions made.\n",
443 printf("Now text is: %s\n\n", text);
445 /** Attempt a substitution **/
446 if (!substitute(&text, "s/Perl/C/")) {
447 printf("substitute: s/Perl/C...No substitution made.\n\n");
450 perl_destruct(my_perl);
454 which produces the output (again, long lines have been wrapped here)
456 perl_match: Text contains the word 'quarter'.
458 perl_match: Text doesn't contain the word 'eighth'.
460 perl_matches: m/(wi..)/g found 2 matches...
464 perl_substitute: s/[aeiou]//gi...139 substitutions made.
465 Now text is: Whn h s t cnvnnc str nd th bll cms t sm mnt lk 76 cnts,
466 Mynrd s wr tht thr s smthng h *shld* d, smthng tht wll nbl hm t gt bck
467 qrtr, bt h hs n d *wht*. H fmbls thrgh hs rd sqzy chngprs nd gvs th by
468 thr xtr pnns wth hs dllr, hpng tht h mght lck nt th crrct mnt. Th by gvs
469 hm bck tw f hs wn pnns nd thn th bg shny qrtr tht s hs prz. -RCHH
471 perl_substitute: s/Perl/C...No substitution made.
473 =head2 Fiddling with the Perl stack from your C program
475 When trying to explain stacks, most computer science textbooks mumble
476 something about spring-loaded columns of cafeteria plates: the last
477 thing you pushed on the stack is the first thing you pop off. That'll
478 do for our purposes: your C program will push some arguments onto "the Perl
479 stack", shut its eyes while some magic happens, and then pop the
480 results--the return value of your Perl subroutine--off the stack.
482 First you'll need to know how to convert between C types and Perl
483 types, with newSViv() and sv_setnv() and newAV() and all their
484 friends. They're described in L<perlguts>.
486 Then you'll need to know how to manipulate the Perl stack. That's
487 described in L<perlcall>.
489 Once you've understood those, embedding Perl in C is easy.
491 Since C has no built-in function for integer exponentiation, let's
492 make Perl's ** operator available to it (this is less useful than it
493 sounds, since Perl implements ** with C's I<pow()> function). First
494 I'll create a stub exponentiation function in I<power.pl>:
501 Now I'll create a C program, I<power.c>, with a function
502 I<PerlPower()> that contains all the perlguts necessary to push the
503 two arguments into I<expo()> and to pop the return value out. Take a
510 static PerlInterpreter *my_perl;
513 PerlPower(int a, int b)
515 dSP; /* initialize stack pointer */
516 ENTER; /* everything created after here */
517 SAVETMPS; /* ...is a temporary variable. */
518 PUSHMARK(sp); /* remember the stack pointer */
519 XPUSHs(sv_2mortal(newSViv(a))); /* push the base onto the stack */
520 XPUSHs(sv_2mortal(newSViv(b))); /* push the exponent onto stack */
521 PUTBACK; /* make local stack pointer global */
522 perl_call_pv("expo", G_SCALAR); /* call the function */
523 SPAGAIN; /* refresh stack pointer */
524 /* pop the return value from stack */
525 printf ("%d to the %dth power is %d.\n", a, b, POPi);
527 FREETMPS; /* free that return value */
528 LEAVE; /* ...and the XPUSHed "mortal" args.*/
531 int main (int argc, char **argv, char **env)
535 my_perl = perl_alloc();
536 perl_construct( my_perl );
538 my_argv[1] = (char *) malloc(10);
539 sprintf(my_argv[1], "power.pl");
541 perl_parse(my_perl, NULL, argc, my_argv, NULL);
543 PerlPower(3, 4); /*** Compute 3 ** 4 ***/
545 perl_destruct(my_perl);
553 % cc -o power power.c `perl -MExtUtils::Embed -e ccopts -e ldopts`
556 3 to the 4th power is 81.
558 =head2 Using Perl modules, which themselves use C libraries, from your C program
560 If you've played with the examples above and tried to embed a script
561 that I<use()>s a Perl module (such as I<Socket>) which itself uses a C or C++ library,
562 this probably happened:
565 Can't load module Socket, dynamic loading not available in this perl.
566 (You may need to build a new perl executable which either supports
567 dynamic loading or has the Socket module statically linked into it.)
572 Your interpreter doesn't know how to communicate with these extensions
573 on its own. A little glue will help. Up until now you've been
574 calling I<perl_parse()>, handing it NULL for the second argument:
576 perl_parse(my_perl, NULL, argc, my_argv, NULL);
578 That's where the glue code can be inserted to create the initial contact between
579 Perl and linked C/C++ routines. Let's take a look some pieces of I<perlmain.c>
580 to see how Perl does this:
584 # define EXTERN_C extern "C"
586 # define EXTERN_C extern
589 static void xs_init _((void));
591 EXTERN_C void boot_DynaLoader _((CV* cv));
592 EXTERN_C void boot_Socket _((CV* cv));
598 char *file = __FILE__;
599 /* DynaLoader is a special case */
600 newXS("DynaLoader::boot_DynaLoader", boot_DynaLoader, file);
601 newXS("Socket::bootstrap", boot_Socket, file);
604 Simply put: for each extension linked with your Perl executable
605 (determined during its initial configuration on your
606 computer or when adding a new extension),
607 a Perl subroutine is created to incorporate the extension's
608 routines. Normally, that subroutine is named
609 I<Module::bootstrap()> and is invoked when you say I<use Module>. In
610 turn, this hooks into an XSUB, I<boot_Module>, which creates a Perl
611 counterpart for each of the extension's XSUBs. Don't worry about this
612 part; leave that to the I<xsubpp> and extension authors. If your
613 extension is dynamically loaded, DynaLoader creates I<Module::bootstrap()>
614 for you on the fly. In fact, if you have a working DynaLoader then there
615 is rarely any need to statically link in any other extensions.
618 Once you have this code, slap it into the second argument of I<perl_parse()>:
621 perl_parse(my_perl, xs_init, argc, my_argv, NULL);
626 % cc -o interp interp.c `perl -MExtUtils::Embed -e ldopts`
630 use SomeDynamicallyLoadedModule;
632 print "Now I can use extensions!\n"'
634 B<ExtUtils::Embed> can also automate writing the I<xs_init> glue code.
636 % perl -MExtUtils::Embed -e xsinit -o perlxsi.c
637 % cc -c perlxsi.c `perl -MExtUtils::Embed -e ccopts`
638 % cc -c interp.c `perl -MExtUtils::Embed -e ccopts`
639 % cc -o interp perlxsi.o interp.o `perl -MExtUtils::Embed -e ldopts`
641 Consult L<perlxs> and L<perlguts> for more details.
646 You can sometimes I<write faster code> in C, but
647 you can always I<write code faster> in Perl. Since you can use
648 each from the other, combine them as you wish.
653 Jon Orwant F<E<lt>orwant@media.mit.eduE<gt>>,
654 co-authored by Doug MacEachern F<E<lt>dougm@osf.orgE<gt>>,
655 with contributions from
656 Tim Bunce, Tom Christiansen, Dov Grobgeld, and Ilya
661 Some of this material is excerpted from my book: I<Perl 5 Interactive>,
662 Waite Group Press, 1996 (ISBN 1-57169-064-6) and appears
663 courtesy of Waite Group Press.