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 L<perlfunc/system> and L<perlfunc/exec>.
21 =item B<Use Perl from Perl?>
23 Read about L<perlfunc/do> and L<perlfunc/eval> and L<perlmod/use>
24 and L<perlmod/require>.
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 five 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 This documentation is UNIX specific.
54 =head2 Compiling your C program
56 Every C program that uses Perl must link in the I<perl library>.
58 What's that, you ask? Perl is itself written in C; the perl library
59 is the collection of compiled C programs that were used to create your
60 perl executable (I</usr/bin/perl> or equivalent). (Corollary: you
61 can't use Perl from your C program unless Perl has been compiled on
62 your machine, or installed properly--that's why you shouldn't blithely
63 copy Perl executables from machine to machine without also copying the
66 Your C program will--usually--allocate, "run", and deallocate a
67 I<PerlInterpreter> object, which is defined in the perl library.
69 If your copy of Perl is recent enough to contain this documentation
70 (5.002 or later), then the perl library (and I<EXTERN.h> and
71 I<perl.h>, which you'll also need) will
72 reside in a directory resembling this:
74 /usr/local/lib/perl5/your_architecture_here/CORE
78 /usr/local/lib/perl5/CORE
80 or maybe something like
84 Execute this statement for a hint about where to find CORE:
86 perl -e 'use Config; print $Config{archlib}'
88 Here's how you might compile the example in the next section,
89 L<Adding a Perl interpreter to your C program>,
90 on a DEC Alpha running the OSF operating system:
92 % cc -o interp interp.c -L/usr/local/lib/perl5/alpha-dec_osf/CORE
93 -I/usr/local/lib/perl5/alpha-dec_osf/CORE -lperl -lm
95 You'll have to choose the appropriate compiler (I<cc>, I<gcc>, et al.) and
96 library directory (I</usr/local/lib/...>) for your machine. If your
97 compiler complains that certain functions are undefined, or that it
98 can't locate I<-lperl>, then you need to change the path following the
99 -L. If it complains that it can't find I<EXTERN.h> or I<perl.h>, you need
100 to change the path following the -I.
102 You may have to add extra libraries as well. Which ones?
103 Perhaps those printed by
105 perl -e 'use Config; print $Config{libs}'
107 =head2 Adding a Perl interpreter to your C program
109 In a sense, perl (the C program) is a good example of embedding Perl
110 (the language), so I'll demonstrate embedding with I<miniperlmain.c>,
111 from the source distribution. Here's a bastardized, non-portable version of
112 I<miniperlmain.c> containing the essentials of embedding:
115 #include <EXTERN.h> /* from the Perl distribution */
116 #include <perl.h> /* from the Perl distribution */
118 static PerlInterpreter *my_perl; /*** The Perl interpreter ***/
120 int main(int argc, char **argv)
122 my_perl = perl_alloc();
123 perl_construct(my_perl);
124 perl_parse(my_perl, NULL, argc, argv, (char **) NULL);
126 perl_destruct(my_perl);
130 Now compile this program (I'll call it I<interp.c>) into an executable:
132 % cc -o interp interp.c -L/usr/local/lib/perl5/alpha-dec_osf/CORE
133 -I/usr/local/lib/perl5/alpha-dec_osf/CORE -lperl -lm
135 After a successful compilation, you'll be able to use I<interp> just
139 print "Pretty Good Perl \n";
140 print "10890 - 9801 is ", 10890 - 9801;
147 % interp -e 'printf("%x", 3735928559)'
150 You can also read and execute Perl statements from a file while in the
151 midst of your C program, by placing the filename in I<argv[1]> before
152 calling I<perl_run()>.
154 =head2 Calling a Perl subroutine from your C program
156 To call individual Perl subroutines, you'll need to remove the call to
157 I<perl_run()> and replace it with a call to I<perl_call_argv()>.
159 That's shown below, in a program I'll call I<showtime.c>.
165 static PerlInterpreter *my_perl;
167 int main(int argc, char **argv)
169 my_perl = perl_alloc();
170 perl_construct(my_perl);
172 perl_parse(my_perl, NULL, argc, argv, (char **) NULL);
174 /*** This replaces perl_run() ***/
175 perl_call_argv("showtime", G_DISCARD | G_NOARGS, argv);
176 perl_destruct(my_perl);
180 where I<showtime> is a Perl subroutine that takes no arguments (that's the
181 I<G_NOARGS>) and for which I'll ignore the return value (that's the
182 I<G_DISCARD>). Those flags, and others, are discussed in L<perlcall>.
184 I'll define the I<showtime> subroutine in a file called I<showtime.pl>:
186 print "I shan't be printed.";
192 Simple enough. Now compile and run:
194 % cc -o showtime showtime.c -L/usr/local/lib/perl5/alpha-dec_osf/CORE
195 -I/usr/local/lib/perl5/alpha-dec_osf/CORE -lperl -lm
197 % showtime showtime.pl
200 yielding the number of seconds that elapsed between January 1, 1970
201 (the beginning of the UNIX epoch), and the moment I began writing this
204 If you want to pass some arguments to the Perl subroutine, or
205 you want to access the return value, you'll need to manipulate the
206 Perl stack, demonstrated in the last section of this document:
207 L<Fiddling with the Perl stack from your C program>
209 =head2 Evaluating a Perl statement from your C program
211 NOTE: This section, and the next, employ some very brittle techniques
212 for evaluting strings of Perl code. Perl 5.002 contains some nifty
213 features that enable A Better Way (such as with L<perlguts/perl_eval_sv>).
214 Look for updates to this document soon.
216 One way to evaluate a Perl string is to define a function (we'll call
217 ours I<perl_eval()>) that wraps around Perl's L<perlfunc/eval>.
219 Arguably, this is the only routine you'll ever need to execute
220 snippets of Perl code from within your C program. Your string can be
221 as long as you wish; it can contain multiple statements; it can
222 use L<perlmod/require> or L<perlfunc/do> to include external Perl
225 Our I<perl_eval()> lets us evaluate individual Perl strings, and then
226 extract variables for coercion into C types. The following program,
227 I<string.c>, executes three Perl strings, extracting an C<int> from
228 the first, a C<float> from the second, and a C<char *> from the third.
234 static PerlInterpreter *my_perl;
236 int perl_eval(char *string)
241 perl_call_argv("_eval_", 0, argv);
244 main (int argc, char **argv)
246 char *embedding[] = { "", "-e", "sub _eval_ { eval $_[0] }" };
249 my_perl = perl_alloc();
250 perl_construct( my_perl );
252 perl_parse(my_perl, NULL, 3, embedding, (char **) NULL);
254 /** Treat $a as an integer **/
255 perl_eval("$a = 3; $a **= 2");
256 printf("a = %d\n", SvIV(perl_get_sv("a", FALSE)));
258 /** Treat $a as a float **/
259 perl_eval("$a = 3.14; $a **= 2");
260 printf("a = %f\n", SvNV(perl_get_sv("a", FALSE)));
262 /** Treat $a as a string **/
263 perl_eval("$a = 'rekcaH lreP rehtonA tsuJ'; $a = reverse($a); ");
264 printf("a = %s\n", SvPV(perl_get_sv("a", FALSE), length));
266 perl_destruct(my_perl);
270 All of those strange functions with I<sv> in their names help convert Perl scalars to C types. They're described in L<perlguts>.
272 If you compile and run I<string.c>, you'll see the results of using
273 I<SvIV()> to create an C<int>, I<SvNV()> to create a C<float>, and
274 I<SvPV()> to create a string:
278 a = Just Another Perl Hacker
281 =head2 Performing Perl pattern matches and substitutions from your C program
283 Our I<perl_eval()> lets us evaluate strings of Perl code, so we can
284 define some functions that use it to "specialize" in matches and
285 substitutions: I<match()>, I<substitute()>, and I<matches()>.
287 char match(char *string, char *pattern);
289 Given a string and a pattern (e.g. "m/clasp/" or "/\b\w*\b/", which in
290 your program might be represented as C<"/\\b\\w*\\b/">),
291 returns 1 if the string matches the pattern and 0 otherwise.
294 int substitute(char *string[], char *pattern);
296 Given a pointer to a string and an "=~" operation (e.g. "s/bob/robert/g" or
297 "tr[A-Z][a-z]"), modifies the string according to the operation,
298 returning the number of substitutions made.
300 int matches(char *string, char *pattern, char **matches[]);
302 Given a string, a pattern, and a pointer to an empty array of strings,
303 evaluates C<$string =~ $pattern> in an array context, and fills in
304 I<matches> with the array elements (allocating memory as it does so),
305 returning the number of matches found.
307 Here's a sample program, I<match.c>, that uses all three:
313 static PerlInterpreter *my_perl;
315 int eval(char *string)
320 perl_call_argv("_eval_", 0, argv);
323 /** match(string, pattern)
325 ** Used for matches in a scalar context.
327 ** Returns 1 if the match was successful; 0 otherwise.
329 char match(char *string, char *pattern)
332 command = malloc(sizeof(char) * strlen(string) + strlen(pattern) + 37);
333 sprintf(command, "$string = '%s'; $return = $string =~ %s",
337 return SvIV(perl_get_sv("return", FALSE));
340 /** substitute(string, pattern)
342 ** Used for =~ operations that modify their left-hand side (s/// and tr///)
344 ** Returns the number of successful matches, and
345 ** modifies the input string if there were any.
347 int substitute(char *string[], char *pattern)
351 command = malloc(sizeof(char) * strlen(*string) + strlen(pattern) + 35);
352 sprintf(command, "$string = '%s'; $ret = ($string =~ %s)",
356 *string = SvPV(perl_get_sv("string", FALSE), length);
357 return SvIV(perl_get_sv("ret", FALSE));
360 /** matches(string, pattern, matches)
362 ** Used for matches in an array context.
364 ** Returns the number of matches,
365 ** and fills in **matches with the matching substrings (allocates memory!)
367 int matches(char *string, char *pattern, char **matches[])
376 command = malloc(sizeof(char) * strlen(string) + strlen(pattern) + 38);
377 sprintf(command, "$string = '%s'; @array = ($string =~ %s)",
381 array = perl_get_av("array", FALSE);
382 num_matches = av_len(array) + 1; /** assume $[ is 0 **/
383 *matches = (char **) malloc(sizeof(char *) * num_matches);
384 for (i = 0; i <= num_matches; i++) {
385 current_match = av_shift(array);
386 (*matches)[i] = SvPV(current_match, length);
391 main (int argc, char **argv)
393 char *embedding[] = { "", "-e", "sub _eval_ { eval $_[0] }" };
394 char *text, **matches;
398 my_perl = perl_alloc();
399 perl_construct( my_perl );
401 perl_parse(my_perl, NULL, 3, embedding, (char **) NULL);
403 text = (char *) malloc(sizeof(char) * 486); /** A long string follows! **/
404 sprintf(text, "%s", "When he is at a convenience store and the bill comes to some amount like 76 cents, Maynard is aware that there is something he *should* do, something that will enable him to get back a quarter, but he has no idea *what*. He fumbles through his red squeezey changepurse and gives the boy three extra pennies with his dollar, hoping that he might luck into the correct amount. The boy gives him back two of his own pennies and then the big shiny quarter that is his prize. -RICHH");
406 if (perl_match(text, "m/quarter/")) /** Does text contain 'quarter'? **/
407 printf("perl_match: Text contains the word 'quarter'.\n\n");
409 printf("perl_match: Text doesn't contain the word 'quarter'.\n\n");
411 if (perl_match(text, "m/eighth/")) /** Does text contain 'eighth'? **/
412 printf("perl_match: Text contains the word 'eighth'.\n\n");
414 printf("perl_match: Text doesn't contain the word 'eighth'.\n\n");
416 /** Match all occurrences of /wi../ **/
417 num_matches = perl_matches(text, "m/(wi..)/g", &matches);
419 printf("perl_matches: m/(wi..)/g found %d matches...\n", num_matches);
420 for (i = 0; i < num_matches; i++)
421 printf("match: %s\n", matches[i]);
423 for (i = 0; i < num_matches; i++) {
428 /** Remove all vowels from text **/
429 num_matches = perl_substitute(&text, "s/[aeiou]//gi");
431 printf("perl_substitute: s/[aeiou]//gi...%d substitutions made.\n",
433 printf("Now text is: %s\n\n", text);
436 /** Attempt a substitution
437 if (!perl_substitute(&text, "s/Perl/C/")) {
438 printf("perl_substitute: s/Perl/C...No substitution made.\n\n");
443 perl_destruct(my_perl);
447 which produces the output
449 perl_match: Text contains the word 'quarter'.
451 perl_match: Text doesn't contain the word 'eighth'.
453 perl_matches: m/(wi..)/g found 2 matches...
457 perl_substitute: s/[aeiou]//gi...139 substitutions made.
458 Now text is: Whn h s t cnvnnc str nd th bll cms t sm mnt lk 76 cnts, Mynrd s wr tht thr s smthng h *shld* d, smthng tht wll nbl hm t gt bck qrtr, bt h hs n d *wht*. H fmbls thrgh hs rd sqzy chngprs nd gvs th by thr xtr pnns wth hs dllr, hpng tht h mght lck nt th crrct mnt. Th by gvs hm bck tw f hs wn pnns nd thn th bg shny qrtr tht s hs prz. -RCHH
460 perl_substitute: s/Perl/C...No substitution made.
462 =head2 Fiddling with the Perl stack from your C program
464 When trying to explain stacks, most computer science textbooks mumble
465 something about spring-loaded columns of cafeteria plates: the last
466 thing you pushed on the stack is the first thing you pop off. That'll
467 do for our purposes: your C program will push some arguments onto "the Perl
468 stack", shut its eyes while some magic happens, and then pop the
469 results--the return value of your Perl subroutine--off the stack.
471 First you'll need to know how to convert between C types and Perl
472 types, with newSViv() and sv_setnv() and newAV() and all their
473 friends. They're described in L<perlguts>.
475 Then you'll need to know how to manipulate the Perl stack. That's
476 described in L<perlcall>.
478 Once you've understood those, embedding Perl in C is easy.
480 Since C has no built-in function for integer exponentiation, let's
481 make Perl's ** operator available to it (this is less useful than it
482 sounds, since Perl implements ** with C's I<pow()> function). First
483 I'll create a stub exponentiation function in I<power.pl>:
490 Now I'll create a C program, I<power.c>, with a function
491 I<PerlPower()> that contains all the perlguts necessary to push the
492 two arguments into I<expo()> and to pop the return value out. Take a
499 static PerlInterpreter *my_perl;
502 PerlPower(int a, int b)
504 dSP; /* initialize stack pointer */
505 ENTER; /* everything created after here */
506 SAVETMPS; /* ...is a temporary variable. */
507 PUSHMARK(sp); /* remember the stack pointer */
508 XPUSHs(sv_2mortal(newSViv(a))); /* push the base onto the stack */
509 XPUSHs(sv_2mortal(newSViv(b))); /* push the exponent onto stack */
510 PUTBACK; /* make local stack pointer global */
511 perl_call_pv("expo", G_SCALAR); /* call the function */
512 SPAGAIN; /* refresh stack pointer */
513 /* pop the return value from stack */
514 printf ("%d to the %dth power is %d.\n", a, b, POPi);
516 FREETMPS; /* free that return value */
517 LEAVE; /* ...and the XPUSHed "mortal" args.*/
520 int main (int argc, char **argv)
524 my_perl = perl_alloc();
525 perl_construct( my_perl );
527 my_argv[1] = (char *) malloc(10);
528 sprintf(my_argv[1], "power.pl");
530 perl_parse(my_perl, NULL, argc, my_argv, (char **) NULL);
532 PerlPower(3, 4); /*** Compute 3 ** 4 ***/
534 perl_destruct(my_perl);
542 % cc -o power power.c -L/usr/local/lib/perl5/alpha-dec_osf/CORE
543 -I/usr/local/lib/perl5/alpha-dec_osf/CORE -lperl -lm
546 3 to the 4th power is 81.
550 You can sometimes I<write faster code> in C, but
551 you can always I<write code faster> in Perl. Since you can use
552 each from the other, combine them as you wish.
557 Jon Orwant F<E<lt>orwant@media.mit.eduE<gt>>, with contributions from
558 Tim Bunce, Tom Christiansen, Dov Grobgeld, and Ilya Zakharevich.
562 Some of this material is excerpted from my book: I<Perl 5 Interactive>,
563 Waite Group Press, 1996 (ISBN 1-57169-064-6) and appears
564 courtesy of Waite Group Press.