@node perlembed, perlapio, perlbook, Top
@unnumbered how to embed perl in your C program


@unnumberedsec NAME

perlembed - how to embed perl in your C program

@unnumberedsec DESCRIPTION

@unnumberedsubsec PREAMBLE

Do you want to:

@table @asis
@item @strong{Use C from Perl?}
Read @xref{perlcall,Perlcall}, and @xref{perlxs,Perlxs},.

@item @strong{Use a UNIX program from Perl?}
Read about backquotes and about system and exec in @xref{perlfunc,Perlfunc},.

@item @strong{Use Perl from Perl?}
Read about do and eval in @xref{perlfunc,Perlfunc}, and use
and require in @xref{perlmod,Perlmod},.

@item @strong{Use C from C?}
Rethink your design.

@item @strong{Use Perl from C?}
Read on...

@end table
@unnumberedsubsec ROADMAP

@samp{Compiling your C program} in this node

There@'s one example in each of the six sections:

@samp{Adding a Perl interpreter to your C program} in this node

@samp{Calling a Perl subroutine from your C program} in this node

@samp{Evaluating a Perl statement from your C program} in this node

@samp{Performing Perl pattern matches and substitutions from your C program} in this node

@samp{Fiddling with the Perl stack from your C program} in this node

@samp{Using Perl modules, which themselves use C libraries, from your C program} in this node

This documentation is UNIX specific.

@unnumberedsubsec Compiling your C program

Every C program that uses Perl must link in the @emph{perl library}.

What@'s that, you ask?  Perl is itself written in C; the perl library
is the collection of compiled C programs that were used to create your
perl executable (@emph{/usr/bin/perl} or equivalent).  (Corollary: you
can@'t use Perl from your C program unless Perl has been compiled on
your machine, or installed properly--that@'s why you shouldn@'t blithely
copy Perl executables from machine to machine without also copying the
@emph{lib} directory.)

Your C program will--usually--allocate, "run", and deallocate a
@emph{PerlInterpreter} object, which is defined in the perl library.

If your copy of Perl is recent enough to contain this documentation
(5.002 or later), then the perl library (and @emph{EXTERN.h} and
@emph{perl.h}, which you@'ll also need) will
reside in a directory resembling this:

@example
/usr/local/lib/perl5/your_architecture_here/CORE
@end example

or perhaps just

@example
/usr/local/lib/perl5/CORE
@end example

or maybe something like

@example
/usr/opt/perl5/CORE
@end example

Execute this statement for a hint about where to find CORE:

@example
perl -MConfig -e @'print $Config@{archlib@}@'
@end example

Here@'s how you might compile the example in the next section,
@samp{Adding a Perl interpreter to your C program} in this node,
on a DEC Alpha running the OSF operating system:

@example
% cc -o interp interp.c -L/usr/local/lib/perl5/alpha-dec_osf/CORE
-I/usr/local/lib/perl5/alpha-dec_osf/CORE -lperl -lm
@end example

You@'ll have to choose the appropriate compiler (@emph{cc}, @emph{gcc}, et al.)  and
library directory (@emph{/usr/local/lib/...})  for your machine.  If your
compiler complains that certain functions are undefined, or that it
can@'t locate @emph{-lperl}, then you need to change the path following the
-L.  If it complains that it can@'t find @emph{EXTERN.h} or @emph{perl.h}, you need
to change the path following the -I.

You may have to add extra libraries as well.  Which ones?
Perhaps those printed by

@example
perl -MConfig -e @'print $Config@{libs@}@'
@end example

We strongly recommend you use the @strong{ExtUtils::Embed} module to determine 
all of this information for you:

@example
% cc -o interp interp.c @`perl -MExtUtils::Embed -e ccopts -e ldopts@`
@end example

If the @strong{ExtUtils::Embed} module is not part of your perl kit@'s
distribution you can retrieve it from:
http://www.perl.com/cgi-bin/cpan_mod?module=ExtUtils::Embed.

@unnumberedsubsec Adding a Perl interpreter to your C program

In a sense, perl (the C program) is a good example of embedding Perl
(the language), so I@'ll demonstrate embedding with @emph{miniperlmain.c},
from the source distribution.  Here@'s a bastardized, non-portable version of
@emph{miniperlmain.c} containing the essentials of embedding:

@example
#include <stdio.h>
#include <EXTERN.h>               /* from the Perl distribution     */
#include <perl.h>                 /* from the Perl distribution     */
@end example

@example
static PerlInterpreter *my_perl;  /***    The Perl interpreter    ***/
@end example

@example
int main(int argc, char **argv, char **env)
@{
    my_perl = perl_alloc();
    perl_construct(my_perl);
    perl_parse(my_perl, NULL, argc, argv, (char **)NULL);
    perl_run(my_perl);
    perl_destruct(my_perl);
    perl_free(my_perl);
@}
@end example

Note that we do not use the @code{env} pointer here or in any of the
following examples.
Normally handed to perl_parse as it@'s final argument,
we hand it a NULL instead, in which case the current environment
is used.

Now compile this program (I@'ll call it @emph{interp.c}) into an executable:

@example
% cc -o interp interp.c @`perl -MExtUtils::Embed -e ccopts -e ldopts@`
@end example

After a successful compilation, you@'ll be able to use @emph{interp} just
like perl itself:

@example
% interp
print "Pretty Good Perl \n";
print "10890 - 9801 is ", 10890 - 9801;
<CTRL-D>
Pretty Good Perl
10890 - 9801 is 1089
@end example

or

@example
% interp -e @'printf("%x", 3735928559)@'
deadbeef
@end example

You can also read and execute Perl statements from a file while in the
midst of your C program, by placing the filename in @emph{argv[1]} before
calling @emph{perl_run()}.

@unnumberedsubsec Calling a Perl subroutine from your C program

To call individual Perl subroutines, you@'ll need to remove the call to
@emph{perl_run()} and replace it with a call to @emph{perl_call_argv()}.

That@'s shown below, in a program I@'ll call @emph{showtime.c}.

@example
#include <stdio.h>
#include <EXTERN.h>
#include <perl.h>
@end example

@example
static PerlInterpreter *my_perl;
@end example

@example
int main(int argc, char **argv, char **env)
@{
    my_perl = perl_alloc();
    perl_construct(my_perl);
@end example

@example
perl_parse(my_perl, NULL, argc, argv, NULL);
@end example

@example
/*** This replaces perl_run() ***/
        perl_call_argv("showtime", G_DISCARD | G_NOARGS, argv);
        perl_destruct(my_perl);
        perl_free(my_perl);
    @}
@end example

where @emph{showtime} is a Perl subroutine that takes no arguments (that@'s the
G_NOARGS) and for which I@'ll ignore the return value (that@'s the
G_DISCARD).  Those flags, and others, are discussed in @xref{perlcall,Perlcall},.

I@'ll define the @emph{showtime} subroutine in a file called @emph{showtime.pl}:

@example
print "I shan@'t be printed.";
@end example

@example
sub showtime @{
    print time;
@}
@end example

Simple enough.  Now compile and run:

@example
% cc -o showtime showtime.c @`perl -MExtUtils::Embed -e ccopts -e ldopts@`
@end example

@example
% showtime showtime.pl
818284590
@end example

yielding the number of seconds that elapsed between January 1, 1970
(the beginning of the UNIX epoch), and the moment I began writing this
sentence.

If you want to pass some arguments to the Perl subroutine, or
you want to access the return value, you@'ll need to manipulate the
Perl stack, demonstrated in the last section of this document:
@samp{Fiddling with the Perl stack from your C program} in this node

@unnumberedsubsec Evaluating a Perl statement from your C program

NOTE: This section, and the next, employ some very brittle techniques
for evaluating strings of Perl code.  Perl 5.002 contains some nifty
features that enable A Better Way (such as with @samp{perl_eval_sv}, @xref{perlguts,Perlguts},).
Look for updates to this document soon.

One way to evaluate a Perl string is to define a function (we@'ll call
ours @emph{perl_eval()}) that wraps around Perl@'s @samp{eval}, @xref{perlfunc,Perlfunc},.

Arguably, this is the only routine you@'ll ever need to execute
snippets of Perl code from within your C program.  Your string can be
as long as you wish; it can contain multiple statements; it can
use @samp{require}, @xref{perlmod,Perlmod}, or @samp{do}, @xref{perlfunc,Perlfunc}, to include external Perl
files.

Our @emph{perl_eval()} lets us evaluate individual Perl strings, and then
extract variables for coercion into C types.  The following program,
@emph{string.c}, executes three Perl strings, extracting an int from
the first, a @code{float} from the second, and a @code{char *} from the third.

@example
#include <stdio.h>
#include <EXTERN.h>
#include <perl.h>
@end example

@example
static PerlInterpreter *my_perl;
@end example

@example
int perl_eval(char *string)
@{
  char *argv[2];
  argv[0] = string;
  argv[1] = NULL;
  perl_call_argv("_eval_", 0, argv);
@}
@end example

@example
main (int argc, char **argv, char **env)
@{
  char *embedding[] = @{ "", "-e", "sub _eval_ @{ eval $_[0] @}" @};
  STRLEN length;
@end example

@example
my_perl = perl_alloc();
perl_construct( my_perl );
@end example

@example
perl_parse(my_perl, NULL, 3, embedding, NULL);
@end example

@example
/** Treat $a as an integer **/
     perl_eval("$a = 3; $a **= 2");
     printf("a = %d\n", SvIV(perl_get_sv("a", FALSE)));
@end example

@example
/** Treat $a as a float **/
     perl_eval("$a = 3.14; $a **= 2");
     printf("a = %f\n", SvNV(perl_get_sv("a", FALSE)));
@end example

@example
/** Treat $a as a string **/
     perl_eval("$a = @'rekcaH lreP rehtonA tsuJ@'; $a = reverse($a); ");
     printf("a = %s\n", SvPV(perl_get_sv("a", FALSE), length));
@end example

@example
perl_destruct(my_perl);
perl_free(my_perl);
   @}
@end example

All of those strange functions with @emph{sv} in their names help convert Perl scalars to C types.  They@'re described in @xref{perlguts,Perlguts},.

If you compile and run @emph{string.c}, you@'ll see the results of using
@emph{SvIV()} to create an int, @emph{SvNV()} to create a @code{float}, and
@emph{SvPV()} to create a string:

@example
a = 9
a = 9.859600
a = Just Another Perl Hacker
@end example

@unnumberedsubsec Performing Perl pattern matches and substitutions from your C program

Our @emph{perl_eval()} lets us evaluate strings of Perl code, so we can
define some functions that use it to "specialize" in matches and
substitutions: @emph{match()}, @emph{substitute()}, and @emph{matches()}.

@example
char match(char *string, char *pattern);
@end example

Given a string and a pattern (e.g. "m/clasp/" or "/\b\w*\b/", which in
your program might be represented as @code{"/\\b\\w*\\b/"}),
returns 1 if the string matches the pattern and 0 otherwise.

@example
int substitute(char *string[], char *pattern);
@end example

Given a pointer to a string and an "=~" operation (e.g. "s/bob/robert/g" or
"tr[A-Z][a-z]"), modifies the string according to the operation,
returning the number of substitutions made.

@example
int matches(char *string, char *pattern, char **matches[]);
@end example

Given a string, a pattern, and a pointer to an empty array of strings,
evaluates @code{$string =~ $pattern} in an array context, and fills in
matches with the array elements (allocating memory as it does so),
returning the number of matches found.

Here@'s a sample program, @emph{match.c}, that uses all three (long lines have
been wrapped here):

@example
#include <stdio.h>
#include <EXTERN.h>
#include <perl.h>
static PerlInterpreter *my_perl;
int perl_eval(char *string)
@{
  char *argv[2];
  argv[0] = string;
  argv[1] = NULL;
  perl_call_argv("_eval_", 0, argv);
@}
/** match(string, pattern)
**
** Used for matches in a scalar context.
**
** Returns 1 if the match was successful; 0 otherwise.
**/
char match(char *string, char *pattern)
@{
  char *command;
  command = malloc(sizeof(char) * strlen(string) + strlen(pattern) + 37);
  sprintf(command, "$string = @'%s@'; $return = $string =~ %s",
	  string, pattern);
  perl_eval(command);
  free(command);
  return SvIV(perl_get_sv("return", FALSE));
@}
/** substitute(string, pattern)
**
** Used for =~ operations that modify their left-hand side (s/// and tr///)
**
** Returns the number of successful matches, and
** modifies the input string if there were any.
**/
int substitute(char *string[], char *pattern)
@{
  char *command;
  STRLEN length;
  command = malloc(sizeof(char) * strlen(*string) + strlen(pattern) + 35);
  sprintf(command, "$string = @'%s@'; $ret = ($string =~ %s)",
	  *string, pattern);
     perl_eval(command);
     free(command);
     *string = SvPV(perl_get_sv("string", FALSE), length);
     return SvIV(perl_get_sv("ret", FALSE));
@}
/** matches(string, pattern, matches)
**
** Used for matches in an array context.
**
** Returns the number of matches,
** and fills in **matches with the matching substrings (allocates memory!)
**/
int matches(char *string, char *pattern, char **match_list[])
@{
  char *command;
  SV *current_match;
  AV *array;
  I32 num_matches;
  STRLEN length;
  int i;
  command = malloc(sizeof(char) * strlen(string) + strlen(pattern) + 38);
  sprintf(command, "$string = @'%s@'; @@array = ($string =~ %s)",
	  string, pattern);
  perl_eval(command);
  free(command);
  array = perl_get_av("array", FALSE);
  num_matches = av_len(array) + 1; /** assume $[ is 0 **/
  *match_list = (char **) malloc(sizeof(char *) * num_matches);
  for (i = 0; i <= num_matches; i++) @{
    current_match = av_shift(array);
    (*match_list)[i] = SvPV(current_match, length);
  @}
  return num_matches;
@}
main (int argc, char **argv, char **env)
@{
  char *embedding[] = @{ "", "-e", "sub _eval_ @{ eval $_[0] @}" @};
  char *text, **match_list;
  int num_matches, i;
  int j;
  my_perl = perl_alloc();
  perl_construct( my_perl );
  perl_parse(my_perl, NULL, 3, embedding, NULL);
  text = (char *) malloc(sizeof(char) * 486); /** A long string follows! **/
  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");
  if (match(text, "m/quarter/")) /** Does text contain @'quarter@'? **/
    printf("match: Text contains the word @'quarter@'.\n\n");
  else
    printf("match: Text doesn@'t contain the word @'quarter@'.\n\n");
  if (match(text, "m/eighth/")) /** Does text contain @'eighth@'? **/
    printf("match: Text contains the word @'eighth@'.\n\n");
  else
    printf("match: Text doesn@'t contain the word @'eighth@'.\n\n");
  /** Match all occurrences of /wi../ **/
  num_matches = matches(text, "m/(wi..)/g", &match_list);
  printf("matches: m/(wi..)/g found %d matches...\n", num_matches);
  for (i = 0; i < num_matches; i++)
    printf("match: %s\n", match_list[i]);
  printf("\n");
  for (i = 0; i < num_matches; i++) @{
    free(match_list[i]);
  @}
  free(match_list);
  /** Remove all vowels from text **/
  num_matches = substitute(&text, "s/[aeiou]//gi");
  if (num_matches) @{
    printf("substitute: s/[aeiou]//gi...%d substitutions made.\n",
	   num_matches);
    printf("Now text is: %s\n\n", text);
  @}
  /** Attempt a substitution **/
  if (!substitute(&text, "s/Perl/C/")) @{
    printf("substitute: s/Perl/C...No substitution made.\n\n");
  @}
  free(text);
  perl_destruct(my_perl);
  perl_free(my_perl);
@}
@end example

which produces the output (again, long lines have been wrapped here)

@example
perl_match: Text contains the word @'quarter@'.
@end example

@example
perl_match: Text doesn@'t contain the word @'eighth@'.
@end example

@example
perl_matches: m/(wi..)/g found 2 matches...
match: will
match: with
@end example

@example
perl_substitute: s/[aeiou]//gi...139 substitutions made.
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
@end example

@example
perl_substitute: s/Perl/C...No substitution made.
@end example

@unnumberedsubsec Fiddling with the Perl stack from your C program

When trying to explain stacks, most computer science textbooks mumble
something about spring-loaded columns of cafeteria plates: the last
thing you pushed on the stack is the first thing you pop off.  That@'ll
do for our purposes: your C program will push some arguments onto "the Perl
stack", shut its eyes while some magic happens, and then pop the
results--the return value of your Perl subroutine--off the stack.

First you@'ll need to know how to convert between C types and Perl
types, with newSViv() and sv_setnv() and newAV() and all their
friends.  They@'re described in @xref{perlguts,Perlguts},.

Then you@'ll need to know how to manipulate the Perl stack.  That@'s
described in @xref{perlcall,Perlcall},.

Once you@'ve understood those, embedding Perl in C is easy.

Since C has no built-in function for integer exponentiation, let@'s
make Perl@'s ** operator available to it (this is less useful than it
sounds, since Perl implements ** with C@'s @emph{pow()} function).  First
I@'ll create a stub exponentiation function in @emph{power.pl}:

@example
sub expo @{
    my ($a, $b) = @@_;
    return $a ** $b;
@}
@end example

Now I@'ll create a C program, @emph{power.c}, with a function
@emph{PerlPower()} that contains all the perlguts necessary to push the
two arguments into @emph{expo()} and to pop the return value out.  Take a
deep breath...

@example
#include <stdio.h>
#include <EXTERN.h>
#include <perl.h>
@end example

@example
static PerlInterpreter *my_perl;
@end example

@example
static void
PerlPower(int a, int b)
@{
  dSP;                            /* initialize stack pointer      */
  ENTER;                          /* everything created after here */
  SAVETMPS;                       /* ...is a temporary variable.   */
  PUSHMARK(sp);                   /* remember the stack pointer    */
  XPUSHs(sv_2mortal(newSViv(a))); /* push the base onto the stack  */
  XPUSHs(sv_2mortal(newSViv(b))); /* push the exponent onto stack  */
  PUTBACK;                      /* make local stack pointer global */
  perl_call_pv("expo", G_SCALAR); /* call the function             */
  SPAGAIN;                        /* refresh stack pointer         */
                                /* pop the return value from stack */
  printf ("%d to the %dth power is %d.\n", a, b, POPi);
  PUTBACK;
  FREETMPS;                       /* free that return value        */
  LEAVE;                       /* ...and the XPUSHed "mortal" args.*/
@}
@end example

@example
int main (int argc, char **argv, char **env)
@{
  char *my_argv[2];
@end example

@example
my_perl = perl_alloc();
perl_construct( my_perl );
@end example

@example
my_argv[1] = (char *) malloc(10);
sprintf(my_argv[1], "power.pl");
@end example

@example
perl_parse(my_perl, NULL, argc, my_argv, NULL);
@end example

@example
PerlPower(3, 4);                      /*** Compute 3 ** 4 ***/
@end example

@example
perl_destruct(my_perl);
perl_free(my_perl);
    @}
@end example

Compile and run:

@example
% cc -o power power.c @`perl -MExtUtils::Embed -e ccopts -e ldopts@`
@end example

@example
% power
3 to the 4th power is 81.
@end example

@unnumberedsubsec Using Perl modules, which themselves use C libraries, from your C program

If you@'ve played with the examples above and tried to embed a script
that @emph{use()}s a Perl module (such as Socket) which itself uses a C or C++ library,
this probably happened:

@example
Can@'t load module Socket, dynamic loading not available in this perl.
 (You may need to build a new perl executable which either supports
 dynamic loading or has the Socket module statically linked into it.)
@end example

What@'s wrong?

Your interpreter doesn@'t know how to communicate with these extensions
on its own.  A little glue will help.  Up until now you@'ve been
calling @emph{perl_parse()}, handing it NULL for the second argument:

@example
perl_parse(my_perl, NULL, argc, my_argv, NULL);
@end example

That@'s where the glue code can be inserted to create the initial contact between
Perl and linked C/C++ routines.  Let@'s take a look some pieces of @emph{perlmain.c}
to see how Perl does this:

@example
#ifdef __cplusplus
#  define EXTERN_C extern "C"
#else
#  define EXTERN_C extern
#endif
@end example

@example
static void xs_init _((void));
@end example

@example
EXTERN_C void boot_DynaLoader _((CV* cv));
EXTERN_C void boot_Socket _((CV* cv));
@end example

@example
EXTERN_C void
xs_init()
@{
       char *file = __FILE__;
       /* DynaLoader is a special case */
       newXS("DynaLoader::boot_DynaLoader", boot_DynaLoader, file);
       newXS("Socket::bootstrap", boot_Socket, file);
@}
@end example

Simply put: for each extension linked with your Perl executable
(determined during its initial configuration on your
computer or when adding a new extension),
a Perl subroutine is created to incorporate the extension@'s
routines.  Normally, that subroutine is named
@emph{Module::bootstrap()} and is invoked when you say @emph{use Module}.  In
turn, this hooks into an XSUB, @emph{boot_Module}, which creates a Perl
counterpart for each of the extension@'s XSUBs.  Don@'t worry about this
part; leave that to the xsubpp and extension authors.  If your
extension is dynamically loaded, DynaLoader creates @emph{Module::bootstrap()}
for you on the fly.  In fact, if you have a working DynaLoader then there
is rarely any need to statically link in any other extensions.

Once you have this code, slap it into the second argument of @emph{perl_parse()}:

@example
perl_parse(my_perl, xs_init, argc, my_argv, NULL);
@end example

Then compile:

@example
% cc -o interp interp.c @`perl -MExtUtils::Embed -e ldopts@`
@end example

@example
% interp
  use Socket;
  use SomeDynamicallyLoadedModule;
@end example

@example
print "Now I can use extensions!\n"@'
@end example

@strong{ExtUtils::Embed} can also automate writing the @emph{xs_init} glue code.

@example
% perl -MExtUtils::Embed -e xsinit -o perlxsi.c
% cc -c perlxsi.c @`perl -MExtUtils::Embed -e ccopts@`
% cc -c interp.c  @`perl -MExtUtils::Embed -e ccopts@`
% cc -o interp perlxsi.o interp.o @`perl -MExtUtils::Embed -e ldopts@`
@end example

Consult @xref{perlxs,Perlxs}, and @xref{perlguts,Perlguts}, for more details.

@unnumberedsec MORAL

You can sometimes @emph{write faster code} in C, but
you can always @emph{write code faster} in Perl.  Since you can use
each from the other, combine them as you wish.

@unnumberedsec AUTHOR

Jon Orwant @file{<orwant@@media.mit.edu>}, 
co-authored by Doug MacEachern @file{<dougm@@osf.org>}, 
with contributions from
Tim Bunce, Tom Christiansen, Dov Grobgeld, and Ilya
Zakharevich.

June 17, 1996

Some of this material is excerpted from my book: @emph{Perl 5 Interactive},
Waite Group Press, 1996 (ISBN 1-57169-064-6) and appears
courtesy of Waite Group Press.
