This is a live mirror of the Perl 5 development currently hosted at https://github.com/perl/perl5
Bleadperl's Win32::Win32 is more recent than the current CPAN release
[perl5.git] / pod / perlembed.pod
CommitLineData
a0d0e21e
LW
1=head1 NAME
2
cb1a09d0 3perlembed - how to embed perl in your C program
a0d0e21e
LW
4
5=head1 DESCRIPTION
6
cb1a09d0
AD
7=head2 PREAMBLE
8
9Do you want to:
10
11=over 5
12
96dbc785 13=item B<Use C from Perl?>
cb1a09d0 14
4929bf7b 15Read L<perlxstut>, L<perlxs>, L<h2xs>, L<perlguts>, and L<perlapi>.
cb1a09d0 16
54310121 17=item B<Use a Unix program from Perl?>
cb1a09d0 18
5f05dabc 19Read about back-quotes and about C<system> and C<exec> in L<perlfunc>.
cb1a09d0 20
96dbc785 21=item B<Use Perl from Perl?>
cb1a09d0 22
e010571f
GS
23Read about L<perlfunc/do> and L<perlfunc/eval> and L<perlfunc/require>
24and L<perlfunc/use>.
cb1a09d0 25
96dbc785 26=item B<Use C from C?>
cb1a09d0
AD
27
28Rethink your design.
29
96dbc785 30=item B<Use Perl from C?>
cb1a09d0
AD
31
32Read on...
33
34=back
35
36=head2 ROADMAP
37
707102d0
GS
38=over 5
39
551e1d92 40=item *
cb1a09d0 41
551e1d92 42Compiling your C program
cb1a09d0 43
551e1d92 44=item *
cb1a09d0 45
551e1d92 46Adding a Perl interpreter to your C program
cb1a09d0 47
551e1d92 48=item *
cb1a09d0 49
551e1d92 50Calling a Perl subroutine from your C program
cb1a09d0 51
551e1d92 52=item *
cb1a09d0 53
551e1d92 54Evaluating a Perl statement from your C program
a6006777 55
551e1d92 56=item *
8ebc5c01 57
551e1d92
RB
58Performing Perl pattern matches and substitutions from your C program
59
60=item *
61
62Fiddling with the Perl stack from your C program
63
64=item *
65
66Maintaining a persistent interpreter
67
68=item *
69
70Maintaining multiple interpreter instances
71
72=item *
73
74Using Perl modules, which themselves use C libraries, from your C program
75
76=item *
77
78Embedding Perl under Win32
96dbc785 79
e010571f 80=back
cb1a09d0
AD
81
82=head2 Compiling your C program
83
8a7dc658
JO
84If you have trouble compiling the scripts in this documentation,
85you're not alone. The cardinal rule: COMPILE THE PROGRAMS IN EXACTLY
86THE SAME WAY THAT YOUR PERL WAS COMPILED. (Sorry for yelling.)
cb1a09d0 87
8a7dc658 88Also, every C program that uses Perl must link in the I<perl library>.
cb1a09d0
AD
89What's that, you ask? Perl is itself written in C; the perl library
90is the collection of compiled C programs that were used to create your
91perl executable (I</usr/bin/perl> or equivalent). (Corollary: you
92can't use Perl from your C program unless Perl has been compiled on
93your machine, or installed properly--that's why you shouldn't blithely
94copy Perl executables from machine to machine without also copying the
95I<lib> directory.)
96
8a7dc658
JO
97When you use Perl from C, your C program will--usually--allocate,
98"run", and deallocate a I<PerlInterpreter> object, which is defined by
99the perl library.
cb1a09d0
AD
100
101If your copy of Perl is recent enough to contain this documentation
a6006777 102(version 5.002 or later), then the perl library (and I<EXTERN.h> and
8a7dc658
JO
103I<perl.h>, which you'll also need) will reside in a directory
104that looks like this:
cb1a09d0
AD
105
106 /usr/local/lib/perl5/your_architecture_here/CORE
107
108or perhaps just
109
110 /usr/local/lib/perl5/CORE
111
112or maybe something like
113
114 /usr/opt/perl5/CORE
115
116Execute this statement for a hint about where to find CORE:
117
96dbc785 118 perl -MConfig -e 'print $Config{archlib}'
cb1a09d0 119
54310121 120Here's how you'd compile the example in the next section,
e010571f 121L<Adding a Perl interpreter to your C program>, on my Linux box:
cb1a09d0 122
54310121 123 % gcc -O2 -Dbool=char -DHAS_BOOL -I/usr/local/include
8a7dc658 124 -I/usr/local/lib/perl5/i586-linux/5.003/CORE
54310121 125 -L/usr/local/lib/perl5/i586-linux/5.003/CORE
8a7dc658 126 -o interp interp.c -lperl -lm
cb1a09d0 127
e010571f
GS
128(That's all one line.) On my DEC Alpha running old 5.003_05, the
129incantation is a bit different:
8a7dc658 130
54310121
PP
131 % cc -O2 -Olimit 2900 -DSTANDARD_C -I/usr/local/include
132 -I/usr/local/lib/perl5/alpha-dec_osf/5.00305/CORE
133 -L/usr/local/lib/perl5/alpha-dec_osf/5.00305/CORE -L/usr/local/lib
8a7dc658
JO
134 -D__LANGUAGE_C__ -D_NO_PROTO -o interp interp.c -lperl -lm
135
136How can you figure out what to add? Assuming your Perl is post-5.001,
137execute a C<perl -V> command and pay special attention to the "cc" and
54310121 138"ccflags" information.
8a7dc658 139
54310121 140You'll have to choose the appropriate compiler (I<cc>, I<gcc>, et al.) for
8a7dc658 141your machine: C<perl -MConfig -e 'print $Config{cc}'> will tell you what
54310121 142to use.
8a7dc658
JO
143
144You'll also have to choose the appropriate library directory
145(I</usr/local/lib/...>) for your machine. If your compiler complains
146that certain functions are undefined, or that it can't locate
147I<-lperl>, then you need to change the path following the C<-L>. If it
148complains that it can't find I<EXTERN.h> and I<perl.h>, you need to
149change the path following the C<-I>.
cb1a09d0
AD
150
151You may have to add extra libraries as well. Which ones?
96dbc785
PP
152Perhaps those printed by
153
154 perl -MConfig -e 'print $Config{libs}'
155
54310121 156Provided your perl binary was properly configured and installed the
8a7dc658
JO
157B<ExtUtils::Embed> module will determine all of this information for
158you:
96dbc785
PP
159
160 % cc -o interp interp.c `perl -MExtUtils::Embed -e ccopts -e ldopts`
161
8a7dc658
JO
162If the B<ExtUtils::Embed> module isn't part of your Perl distribution,
163you can retrieve it from
f224927c
JH
164http://www.perl.com/perl/CPAN/modules/by-module/ExtUtils/
165(If this documentation came from your Perl distribution, then you're
8a7dc658 166running 5.004 or better and you already have it.)
96dbc785 167
8a7dc658 168The B<ExtUtils::Embed> kit on CPAN also contains all source code for
54310121 169the examples in this document, tests, additional examples and other
8a7dc658 170information you may find useful.
cb1a09d0
AD
171
172=head2 Adding a Perl interpreter to your C program
173
174In a sense, perl (the C program) is a good example of embedding Perl
175(the language), so I'll demonstrate embedding with I<miniperlmain.c>,
e010571f 176included in the source distribution. Here's a bastardized, nonportable
8a7dc658 177version of I<miniperlmain.c> containing the essentials of embedding:
cb1a09d0 178
cb1a09d0
AD
179 #include <EXTERN.h> /* from the Perl distribution */
180 #include <perl.h> /* from the Perl distribution */
96dbc785 181
cb1a09d0 182 static PerlInterpreter *my_perl; /*** The Perl interpreter ***/
96dbc785 183
c07a80fd 184 int main(int argc, char **argv, char **env)
cb1a09d0 185 {
1ccffcf5 186 PERL_SYS_INIT3(&argc,&argv,&env);
cb1a09d0
AD
187 my_perl = perl_alloc();
188 perl_construct(my_perl);
d95b23b2 189 PL_exit_flags |= PERL_EXIT_DESTRUCT_END;
96dbc785 190 perl_parse(my_perl, NULL, argc, argv, (char **)NULL);
cb1a09d0
AD
191 perl_run(my_perl);
192 perl_destruct(my_perl);
193 perl_free(my_perl);
1ccffcf5 194 PERL_SYS_TERM();
cb1a09d0
AD
195 }
196
8a7dc658
JO
197Notice that we don't use the C<env> pointer. Normally handed to
198C<perl_parse> as its final argument, C<env> here is replaced by
1ccffcf5
IZ
199C<NULL>, which means that the current environment will be used. The macros
200PERL_SYS_INIT3() and PERL_SYS_TERM() provide system-specific tune up
201of the C runtime environment necessary to run Perl interpreters; since
202PERL_SYS_INIT3() may change C<env>, it may be more appropriate to provide
203C<env> as an argument to perl_parse().
96dbc785 204
cb1a09d0
AD
205Now compile this program (I'll call it I<interp.c>) into an executable:
206
96dbc785 207 % cc -o interp interp.c `perl -MExtUtils::Embed -e ccopts -e ldopts`
cb1a09d0
AD
208
209After a successful compilation, you'll be able to use I<interp> just
210like perl itself:
211
212 % interp
213 print "Pretty Good Perl \n";
214 print "10890 - 9801 is ", 10890 - 9801;
215 <CTRL-D>
216 Pretty Good Perl
217 10890 - 9801 is 1089
218
219or
220
221 % interp -e 'printf("%x", 3735928559)'
222 deadbeef
223
224You can also read and execute Perl statements from a file while in the
225midst of your C program, by placing the filename in I<argv[1]> before
e010571f 226calling I<perl_run>.
cb1a09d0
AD
227
228=head2 Calling a Perl subroutine from your C program
229
4929bf7b 230To call individual Perl subroutines, you can use any of the B<call_*>
7b8d334a 231functions documented in L<perlcall>.
4929bf7b 232In this example we'll use C<call_argv>.
cb1a09d0
AD
233
234That's shown below, in a program I'll call I<showtime.c>.
235
cb1a09d0 236 #include <EXTERN.h>
96dbc785
PP
237 #include <perl.h>
238
239 static PerlInterpreter *my_perl;
240
c07a80fd 241 int main(int argc, char **argv, char **env)
cb1a09d0 242 {
8ebc5c01 243 char *args[] = { NULL };
1ccffcf5 244 PERL_SYS_INIT3(&argc,&argv,&env);
cb1a09d0
AD
245 my_perl = perl_alloc();
246 perl_construct(my_perl);
96dbc785
PP
247
248 perl_parse(my_perl, NULL, argc, argv, NULL);
d95b23b2 249 PL_exit_flags |= PERL_EXIT_DESTRUCT_END;
96dbc785 250
8ebc5c01
PP
251 /*** skipping perl_run() ***/
252
4929bf7b 253 call_argv("showtime", G_DISCARD | G_NOARGS, args);
8ebc5c01 254
cb1a09d0
AD
255 perl_destruct(my_perl);
256 perl_free(my_perl);
1ccffcf5 257 PERL_SYS_TERM();
cb1a09d0
AD
258 }
259
260where I<showtime> is a Perl subroutine that takes no arguments (that's the
96dbc785 261I<G_NOARGS>) and for which I'll ignore the return value (that's the
cb1a09d0
AD
262I<G_DISCARD>). Those flags, and others, are discussed in L<perlcall>.
263
264I'll define the I<showtime> subroutine in a file called I<showtime.pl>:
265
266 print "I shan't be printed.";
96dbc785 267
cb1a09d0
AD
268 sub showtime {
269 print time;
270 }
271
272Simple enough. Now compile and run:
273
96dbc785
PP
274 % cc -o showtime showtime.c `perl -MExtUtils::Embed -e ccopts -e ldopts`
275
cb1a09d0
AD
276 % showtime showtime.pl
277 818284590
278
279yielding the number of seconds that elapsed between January 1, 1970
8a7dc658 280(the beginning of the Unix epoch), and the moment I began writing this
cb1a09d0
AD
281sentence.
282
d95b23b2
AB
283In this particular case we don't have to call I<perl_run>, as we set
284the PL_exit_flag PERL_EXIT_DESTRUCT_END which executes END blocks in
285perl_destruct.
8ebc5c01 286
8a7dc658
JO
287If you want to pass arguments to the Perl subroutine, you can add
288strings to the C<NULL>-terminated C<args> list passed to
4929bf7b 289I<call_argv>. For other data types, or to examine return values,
13a2d996
SP
290you'll need to manipulate the Perl stack. That's demonstrated in
291L<Fiddling with the Perl stack from your C program>.
cb1a09d0
AD
292
293=head2 Evaluating a Perl statement from your C program
294
137443ea 295Perl provides two API functions to evaluate pieces of Perl code.
4929bf7b 296These are L<perlapi/eval_sv> and L<perlapi/eval_pv>.
137443ea
PP
297
298Arguably, these are the only routines you'll ever need to execute
e010571f
GS
299snippets of Perl code from within your C program. Your code can be as
300long as you wish; it can contain multiple statements; it can employ
301L<perlfunc/use>, L<perlfunc/require>, and L<perlfunc/do> to
302include external Perl files.
cb1a09d0 303
4929bf7b 304I<eval_pv> lets us evaluate individual Perl strings, and then
96dbc785 305extract variables for coercion into C types. The following program,
cb1a09d0
AD
306I<string.c>, executes three Perl strings, extracting an C<int> from
307the first, a C<float> from the second, and a C<char *> from the third.
308
cb1a09d0
AD
309 #include <EXTERN.h>
310 #include <perl.h>
c47ff5f1 311
cb1a09d0 312 static PerlInterpreter *my_perl;
c47ff5f1 313
c07a80fd 314 main (int argc, char **argv, char **env)
cb1a09d0 315 {
2d8e6c8d 316 STRLEN n_a;
137443ea 317 char *embedding[] = { "", "-e", "0" };
c47ff5f1 318
1ccffcf5 319 PERL_SYS_INIT3(&argc,&argv,&env);
137443ea
PP
320 my_perl = perl_alloc();
321 perl_construct( my_perl );
c47ff5f1 322
137443ea 323 perl_parse(my_perl, NULL, 3, embedding, NULL);
d95b23b2 324 PL_exit_flags |= PERL_EXIT_DESTRUCT_END;
137443ea 325 perl_run(my_perl);
c47ff5f1 326
137443ea 327 /** Treat $a as an integer **/
4929bf7b
GS
328 eval_pv("$a = 3; $a **= 2", TRUE);
329 printf("a = %d\n", SvIV(get_sv("a", FALSE)));
c47ff5f1 330
137443ea 331 /** Treat $a as a float **/
4929bf7b
GS
332 eval_pv("$a = 3.14; $a **= 2", TRUE);
333 printf("a = %f\n", SvNV(get_sv("a", FALSE)));
c47ff5f1 334
137443ea 335 /** Treat $a as a string **/
4929bf7b
GS
336 eval_pv("$a = 'rekcaH lreP rehtonA tsuJ'; $a = reverse($a);", TRUE);
337 printf("a = %s\n", SvPV(get_sv("a", FALSE), n_a));
c47ff5f1 338
137443ea
PP
339 perl_destruct(my_perl);
340 perl_free(my_perl);
1ccffcf5 341 PERL_SYS_TERM();
cb1a09d0
AD
342 }
343
4929bf7b 344All of those strange functions with I<sv> in their names help convert Perl scalars to C types. They're described in L<perlguts> and L<perlapi>.
cb1a09d0
AD
345
346If you compile and run I<string.c>, you'll see the results of using
347I<SvIV()> to create an C<int>, I<SvNV()> to create a C<float>, and
348I<SvPV()> to create a string:
349
350 a = 9
351 a = 9.859600
352 a = Just Another Perl Hacker
353
8f183262
DM
354In the example above, we've created a global variable to temporarily
355store the computed value of our eval'd expression. It is also
356possible and in most cases a better strategy to fetch the return value
4929bf7b 357from I<eval_pv()> instead. Example:
8f183262 358
8f183262 359 ...
2d8e6c8d 360 STRLEN n_a;
4929bf7b 361 SV *val = eval_pv("reverse 'rekcaH lreP rehtonA tsuJ'", TRUE);
2d8e6c8d 362 printf("%s\n", SvPV(val,n_a));
8f183262
DM
363 ...
364
365This way, we avoid namespace pollution by not creating global
366variables and we've simplified our code as well.
cb1a09d0
AD
367
368=head2 Performing Perl pattern matches and substitutions from your C program
369
4929bf7b 370The I<eval_sv()> function lets us evaluate strings of Perl code, so we can
cb1a09d0
AD
371define some functions that use it to "specialize" in matches and
372substitutions: I<match()>, I<substitute()>, and I<matches()>.
373
e010571f 374 I32 match(SV *string, char *pattern);
cb1a09d0 375
8a7dc658
JO
376Given a string and a pattern (e.g., C<m/clasp/> or C</\b\w*\b/>, which
377in your C program might appear as "/\\b\\w*\\b/"), match()
cb1a09d0
AD
378returns 1 if the string matches the pattern and 0 otherwise.
379
1f05cdcd 380 int substitute(SV **string, char *pattern);
cb1a09d0 381
1f05cdcd 382Given a pointer to an C<SV> and an C<=~> operation (e.g.,
8a7dc658 383C<s/bob/robert/g> or C<tr[A-Z][a-z]>), substitute() modifies the string
bf9cdc68 384within the C<SV> as according to the operation, returning the number of substitutions
8a7dc658 385made.
cb1a09d0 386
1f05cdcd 387 int matches(SV *string, char *pattern, AV **matches);
cb1a09d0 388
1f05cdcd 389Given an C<SV>, a pattern, and a pointer to an empty C<AV>,
90fdbbb7 390matches() evaluates C<$string =~ $pattern> in a list context, and
1f05cdcd 391fills in I<matches> with the array elements, returning the number of matches found.
cb1a09d0 392
96dbc785
PP
393Here's a sample program, I<match.c>, that uses all three (long lines have
394been wrapped here):
cb1a09d0 395
1f05cdcd
DM
396 #include <EXTERN.h>
397 #include <perl.h>
c47ff5f1 398
7fef744d
BD
399 static PerlInterpreter *my_perl;
400
4929bf7b
GS
401 /** my_eval_sv(code, error_check)
402 ** kinda like eval_sv(),
1f05cdcd
DM
403 ** but we pop the return value off the stack
404 **/
4929bf7b 405 SV* my_eval_sv(SV *sv, I32 croak_on_error)
1f05cdcd
DM
406 {
407 dSP;
408 SV* retval;
2d8e6c8d 409 STRLEN n_a;
c47ff5f1 410
924508f0 411 PUSHMARK(SP);
4929bf7b 412 eval_sv(sv, G_SCALAR);
c47ff5f1 413
1f05cdcd
DM
414 SPAGAIN;
415 retval = POPs;
416 PUTBACK;
c47ff5f1 417
9cde0e7f 418 if (croak_on_error && SvTRUE(ERRSV))
2d8e6c8d 419 croak(SvPVx(ERRSV, n_a));
c47ff5f1 420
1f05cdcd
DM
421 return retval;
422 }
c47ff5f1 423
1f05cdcd
DM
424 /** match(string, pattern)
425 **
426 ** Used for matches in a scalar context.
427 **
428 ** Returns 1 if the match was successful; 0 otherwise.
429 **/
c47ff5f1 430
1f05cdcd
DM
431 I32 match(SV *string, char *pattern)
432 {
8c52afec 433 SV *command = NEWSV(1099, 0), *retval;
2d8e6c8d 434 STRLEN n_a;
c47ff5f1 435
1f05cdcd 436 sv_setpvf(command, "my $string = '%s'; $string =~ %s",
2d8e6c8d 437 SvPV(string,n_a), pattern);
c47ff5f1 438
4929bf7b 439 retval = my_eval_sv(command, TRUE);
1f05cdcd 440 SvREFCNT_dec(command);
c47ff5f1 441
1f05cdcd
DM
442 return SvIV(retval);
443 }
c47ff5f1 444
1f05cdcd
DM
445 /** substitute(string, pattern)
446 **
447 ** Used for =~ operations that modify their left-hand side (s/// and tr///)
448 **
449 ** Returns the number of successful matches, and
450 ** modifies the input string if there were any.
451 **/
c47ff5f1 452
1f05cdcd
DM
453 I32 substitute(SV **string, char *pattern)
454 {
8c52afec 455 SV *command = NEWSV(1099, 0), *retval;
2d8e6c8d 456 STRLEN n_a;
c47ff5f1 457
1f05cdcd 458 sv_setpvf(command, "$string = '%s'; ($string =~ %s)",
2d8e6c8d 459 SvPV(*string,n_a), pattern);
c47ff5f1 460
4929bf7b 461 retval = my_eval_sv(command, TRUE);
1f05cdcd 462 SvREFCNT_dec(command);
c47ff5f1 463
4929bf7b 464 *string = get_sv("string", FALSE);
1f05cdcd
DM
465 return SvIV(retval);
466 }
c47ff5f1 467
1f05cdcd
DM
468 /** matches(string, pattern, matches)
469 **
90fdbbb7 470 ** Used for matches in a list context.
1f05cdcd
DM
471 **
472 ** Returns the number of matches,
473 ** and fills in **matches with the matching substrings
474 **/
c47ff5f1 475
1f05cdcd
DM
476 I32 matches(SV *string, char *pattern, AV **match_list)
477 {
8c52afec 478 SV *command = NEWSV(1099, 0);
cb1a09d0 479 I32 num_matches;
2d8e6c8d 480 STRLEN n_a;
c47ff5f1 481
1f05cdcd 482 sv_setpvf(command, "my $string = '%s'; @array = ($string =~ %s)",
2d8e6c8d 483 SvPV(string,n_a), pattern);
c47ff5f1 484
4929bf7b 485 my_eval_sv(command, TRUE);
1f05cdcd 486 SvREFCNT_dec(command);
c47ff5f1 487
4929bf7b 488 *match_list = get_av("array", FALSE);
1f05cdcd 489 num_matches = av_len(*match_list) + 1; /** assume $[ is 0 **/
c47ff5f1 490
cb1a09d0 491 return num_matches;
1f05cdcd 492 }
c47ff5f1 493
1f05cdcd
DM
494 main (int argc, char **argv, char **env)
495 {
a6006777 496 char *embedding[] = { "", "-e", "0" };
1f05cdcd
DM
497 AV *match_list;
498 I32 num_matches, i;
7fef744d 499 SV *text;
2d8e6c8d 500 STRLEN n_a;
c47ff5f1 501
1ccffcf5 502 PERL_SYS_INIT3(&argc,&argv,&env);
7fef744d 503 my_perl = perl_alloc();
1f05cdcd 504 perl_construct(my_perl);
96dbc785 505 perl_parse(my_perl, NULL, 3, embedding, NULL);
d95b23b2 506 PL_exit_flags |= PERL_EXIT_DESTRUCT_END;
c47ff5f1 507
7fef744d 508 text = NEWSV(1099,0);
d3f3bf9f
RGS
509 sv_setpv(text, "When he is at a convenience store and the "
510 "bill comes to some amount like 76 cents, Maynard is "
511 "aware that there is something he *should* do, something "
512 "that will enable him to get back a quarter, but he has "
513 "no idea *what*. He fumbles through his red squeezey "
514 "changepurse and gives the boy three extra pennies with "
515 "his dollar, hoping that he might luck into the correct "
516 "amount. The boy gives him back two of his own pennies "
517 "and then the big shiny quarter that is his prize. "
518 "-RICHH");
c47ff5f1 519
96dbc785 520 if (match(text, "m/quarter/")) /** Does text contain 'quarter'? **/
1f05cdcd 521 printf("match: Text contains the word 'quarter'.\n\n");
96dbc785 522 else
1f05cdcd 523 printf("match: Text doesn't contain the word 'quarter'.\n\n");
c47ff5f1 524
96dbc785 525 if (match(text, "m/eighth/")) /** Does text contain 'eighth'? **/
1f05cdcd 526 printf("match: Text contains the word 'eighth'.\n\n");
96dbc785 527 else
1f05cdcd 528 printf("match: Text doesn't contain the word 'eighth'.\n\n");
c47ff5f1 529
96dbc785
PP
530 /** Match all occurrences of /wi../ **/
531 num_matches = matches(text, "m/(wi..)/g", &match_list);
532 printf("matches: m/(wi..)/g found %d matches...\n", num_matches);
c47ff5f1 533
96dbc785 534 for (i = 0; i < num_matches; i++)
2d8e6c8d 535 printf("match: %s\n", SvPV(*av_fetch(match_list, i, FALSE),n_a));
cb1a09d0 536 printf("\n");
c47ff5f1 537
96dbc785
PP
538 /** Remove all vowels from text **/
539 num_matches = substitute(&text, "s/[aeiou]//gi");
cb1a09d0 540 if (num_matches) {
1f05cdcd
DM
541 printf("substitute: s/[aeiou]//gi...%d substitutions made.\n",
542 num_matches);
2d8e6c8d 543 printf("Now text is: %s\n\n", SvPV(text,n_a));
cb1a09d0 544 }
c47ff5f1 545
96dbc785
PP
546 /** Attempt a substitution **/
547 if (!substitute(&text, "s/Perl/C/")) {
1f05cdcd 548 printf("substitute: s/Perl/C...No substitution made.\n\n");
cb1a09d0 549 }
c47ff5f1 550
1f05cdcd 551 SvREFCNT_dec(text);
9cde0e7f 552 PL_perl_destruct_level = 1;
cb1a09d0
AD
553 perl_destruct(my_perl);
554 perl_free(my_perl);
1ccffcf5 555 PERL_SYS_TERM();
1f05cdcd 556 }
cb1a09d0 557
96dbc785 558which produces the output (again, long lines have been wrapped here)
cb1a09d0 559
8a7dc658 560 match: Text contains the word 'quarter'.
96dbc785 561
8a7dc658 562 match: Text doesn't contain the word 'eighth'.
96dbc785 563
8a7dc658 564 matches: m/(wi..)/g found 2 matches...
cb1a09d0
AD
565 match: will
566 match: with
96dbc785 567
8a7dc658 568 substitute: s/[aeiou]//gi...139 substitutions made.
54310121 569 Now text is: Whn h s t cnvnnc str nd th bll cms t sm mnt lk 76 cnts,
96dbc785
PP
570 Mynrd s wr tht thr s smthng h *shld* d, smthng tht wll nbl hm t gt bck
571 qrtr, bt h hs n d *wht*. H fmbls thrgh hs rd sqzy chngprs nd gvs th by
572 thr xtr pnns wth hs dllr, hpng tht h mght lck nt th crrct mnt. Th by gvs
573 hm bck tw f hs wn pnns nd thn th bg shny qrtr tht s hs prz. -RCHH
574
8a7dc658 575 substitute: s/Perl/C...No substitution made.
96dbc785 576
cb1a09d0
AD
577=head2 Fiddling with the Perl stack from your C program
578
579When trying to explain stacks, most computer science textbooks mumble
580something about spring-loaded columns of cafeteria plates: the last
581thing you pushed on the stack is the first thing you pop off. That'll
582do for our purposes: your C program will push some arguments onto "the Perl
583stack", shut its eyes while some magic happens, and then pop the
584results--the return value of your Perl subroutine--off the stack.
96dbc785 585
cb1a09d0
AD
586First you'll need to know how to convert between C types and Perl
587types, with newSViv() and sv_setnv() and newAV() and all their
4929bf7b 588friends. They're described in L<perlguts> and L<perlapi>.
cb1a09d0
AD
589
590Then you'll need to know how to manipulate the Perl stack. That's
591described in L<perlcall>.
592
96dbc785 593Once you've understood those, embedding Perl in C is easy.
cb1a09d0 594
54310121 595Because C has no builtin function for integer exponentiation, let's
cb1a09d0 596make Perl's ** operator available to it (this is less useful than it
5f05dabc 597sounds, because Perl implements ** with C's I<pow()> function). First
cb1a09d0
AD
598I'll create a stub exponentiation function in I<power.pl>:
599
600 sub expo {
601 my ($a, $b) = @_;
602 return $a ** $b;
603 }
604
605Now I'll create a C program, I<power.c>, with a function
606I<PerlPower()> that contains all the perlguts necessary to push the
607two arguments into I<expo()> and to pop the return value out. Take a
608deep breath...
609
cb1a09d0
AD
610 #include <EXTERN.h>
611 #include <perl.h>
96dbc785 612
cb1a09d0 613 static PerlInterpreter *my_perl;
96dbc785 614
cb1a09d0
AD
615 static void
616 PerlPower(int a, int b)
617 {
618 dSP; /* initialize stack pointer */
619 ENTER; /* everything created after here */
620 SAVETMPS; /* ...is a temporary variable. */
924508f0 621 PUSHMARK(SP); /* remember the stack pointer */
cb1a09d0
AD
622 XPUSHs(sv_2mortal(newSViv(a))); /* push the base onto the stack */
623 XPUSHs(sv_2mortal(newSViv(b))); /* push the exponent onto stack */
624 PUTBACK; /* make local stack pointer global */
4929bf7b 625 call_pv("expo", G_SCALAR); /* call the function */
cb1a09d0
AD
626 SPAGAIN; /* refresh stack pointer */
627 /* pop the return value from stack */
628 printf ("%d to the %dth power is %d.\n", a, b, POPi);
96dbc785 629 PUTBACK;
cb1a09d0
AD
630 FREETMPS; /* free that return value */
631 LEAVE; /* ...and the XPUSHed "mortal" args.*/
632 }
96dbc785
PP
633
634 int main (int argc, char **argv, char **env)
cb1a09d0 635 {
95b76e31 636 char *my_argv[] = { "", "power.pl" };
96dbc785 637
1ccffcf5 638 PERL_SYS_INIT3(&argc,&argv,&env);
cb1a09d0
AD
639 my_perl = perl_alloc();
640 perl_construct( my_perl );
96dbc785 641
95b76e31 642 perl_parse(my_perl, NULL, 2, my_argv, (char **)NULL);
d95b23b2 643 PL_exit_flags |= PERL_EXIT_DESTRUCT_END;
8ebc5c01 644 perl_run(my_perl);
96dbc785 645
cb1a09d0 646 PerlPower(3, 4); /*** Compute 3 ** 4 ***/
96dbc785 647
cb1a09d0
AD
648 perl_destruct(my_perl);
649 perl_free(my_perl);
1ccffcf5 650 PERL_SYS_TERM();
cb1a09d0 651 }
96dbc785 652
cb1a09d0
AD
653
654
655Compile and run:
656
96dbc785
PP
657 % cc -o power power.c `perl -MExtUtils::Embed -e ccopts -e ldopts`
658
659 % power
cb1a09d0
AD
660 3 to the 4th power is 81.
661
a6006777
PP
662=head2 Maintaining a persistent interpreter
663
8a7dc658
JO
664When developing interactive and/or potentially long-running
665applications, it's a good idea to maintain a persistent interpreter
666rather than allocating and constructing a new interpreter multiple
667times. The major reason is speed: since Perl will only be loaded into
54310121 668memory once.
8a7dc658
JO
669
670However, you have to be more cautious with namespace and variable
671scoping when using a persistent interpreter. In previous examples
672we've been using global variables in the default package C<main>. We
673knew exactly what code would be run, and assumed we could avoid
674variable collisions and outrageous symbol table growth.
675
676Let's say your application is a server that will occasionally run Perl
677code from some arbitrary file. Your server has no way of knowing what
678code it's going to run. Very dangerous.
679
680If the file is pulled in by C<perl_parse()>, compiled into a newly
681constructed interpreter, and subsequently cleaned out with
682C<perl_destruct()> afterwards, you're shielded from most namespace
683troubles.
684
685One way to avoid namespace collisions in this scenario is to translate
686the filename into a guaranteed-unique package name, and then compile
e010571f 687the code into that package using L<perlfunc/eval>. In the example
8a7dc658
JO
688below, each file will only be compiled once. Or, the application
689might choose to clean out the symbol table associated with the file
4929bf7b 690after it's no longer needed. Using L<perlapi/call_argv>, We'll
8a7dc658
JO
691call the subroutine C<Embed::Persistent::eval_file> which lives in the
692file C<persistent.pl> and pass the filename and boolean cleanup/cache
a6006777
PP
693flag as arguments.
694
8a7dc658
JO
695Note that the process will continue to grow for each file that it
696uses. In addition, there might be C<AUTOLOAD>ed subroutines and other
697conditions that cause Perl's symbol table to grow. You might want to
698add some logic that keeps track of the process size, or restarts
699itself after a certain number of requests, to ensure that memory
700consumption is minimized. You'll also want to scope your variables
e010571f 701with L<perlfunc/my> whenever possible.
a6006777 702
54310121 703
a6006777
PP
704 package Embed::Persistent;
705 #persistent.pl
54310121 706
a6006777 707 use strict;
77ca0c92 708 our %Cache;
1ee082b7 709 use Symbol qw(delete_package);
54310121 710
a6006777
PP
711 sub valid_package_name {
712 my($string) = @_;
713 $string =~ s/([^A-Za-z0-9\/])/sprintf("_%2x",unpack("C",$1))/eg;
714 # second pass only for words starting with a digit
715 $string =~ s|/(\d)|sprintf("/_%2x",unpack("C",$1))|eg;
54310121 716
a6006777
PP
717 # Dress it up as a real package name
718 $string =~ s|/|::|g;
719 return "Embed" . $string;
720 }
54310121 721
a6006777
PP
722 sub eval_file {
723 my($filename, $delete) = @_;
724 my $package = valid_package_name($filename);
725 my $mtime = -M $filename;
726 if(defined $Cache{$package}{mtime}
727 &&
54310121 728 $Cache{$package}{mtime} <= $mtime)
a6006777 729 {
54310121 730 # we have compiled this subroutine already,
8ebc5c01
PP
731 # it has not been updated on disk, nothing left to do
732 print STDERR "already compiled $package->handler\n";
a6006777
PP
733 }
734 else {
8ebc5c01
PP
735 local *FH;
736 open FH, $filename or die "open '$filename' $!";
737 local($/) = undef;
738 my $sub = <FH>;
739 close FH;
54310121 740
8ebc5c01
PP
741 #wrap the code into a subroutine inside our unique package
742 my $eval = qq{package $package; sub handler { $sub; }};
743 {
744 # hide our variables within this block
745 my($filename,$mtime,$package,$sub);
746 eval $eval;
747 }
748 die $@ if $@;
54310121 749
8ebc5c01
PP
750 #cache it unless we're cleaning out each time
751 $Cache{$package}{mtime} = $mtime unless $delete;
a6006777 752 }
54310121 753
a6006777
PP
754 eval {$package->handler;};
755 die $@ if $@;
54310121 756
a6006777 757 delete_package($package) if $delete;
54310121 758
a6006777
PP
759 #take a look if you want
760 #print Devel::Symdump->rnew($package)->as_string, $/;
761 }
54310121 762
a6006777 763 1;
54310121 764
a6006777
PP
765 __END__
766
767 /* persistent.c */
54310121
PP
768 #include <EXTERN.h>
769 #include <perl.h>
770
a6006777
PP
771 /* 1 = clean out filename's symbol table after each request, 0 = don't */
772 #ifndef DO_CLEAN
773 #define DO_CLEAN 0
774 #endif
54310121 775
2307c6d0
SB
776 #define BUFFER_SIZE 1024
777
7fef744d 778 static PerlInterpreter *my_perl = NULL;
54310121 779
a6006777
PP
780 int
781 main(int argc, char **argv, char **env)
782 {
783 char *embedding[] = { "", "persistent.pl" };
784 char *args[] = { "", DO_CLEAN, NULL };
2307c6d0 785 char filename[BUFFER_SIZE];
a6006777 786 int exitstatus = 0;
2d8e6c8d 787 STRLEN n_a;
54310121 788
1ccffcf5 789 PERL_SYS_INIT3(&argc,&argv,&env);
7fef744d 790 if((my_perl = perl_alloc()) == NULL) {
8ebc5c01
PP
791 fprintf(stderr, "no memory!");
792 exit(1);
a6006777 793 }
7fef744d 794 perl_construct(my_perl);
54310121 795
7fef744d 796 exitstatus = perl_parse(my_perl, NULL, 2, embedding, NULL);
d95b23b2 797 PL_exit_flags |= PERL_EXIT_DESTRUCT_END;
54310121 798 if(!exitstatus) {
7fef744d 799 exitstatus = perl_run(my_perl);
54310121 800
2307c6d0
SB
801 while(printf("Enter file name: ") &&
802 fgets(filename, BUFFER_SIZE, stdin)) {
54310121 803
2307c6d0 804 filename[strlen(filename)-1] = '\0'; /* strip \n */
8ebc5c01
PP
805 /* call the subroutine, passing it the filename as an argument */
806 args[0] = filename;
4929bf7b 807 call_argv("Embed::Persistent::eval_file",
8ebc5c01 808 G_DISCARD | G_EVAL, args);
54310121 809
8ebc5c01 810 /* check $@ */
9cde0e7f 811 if(SvTRUE(ERRSV))
2d8e6c8d 812 fprintf(stderr, "eval error: %s\n", SvPV(ERRSV,n_a));
8ebc5c01 813 }
a6006777 814 }
54310121 815
9cde0e7f 816 PL_perl_destruct_level = 0;
7fef744d
BD
817 perl_destruct(my_perl);
818 perl_free(my_perl);
1ccffcf5 819 PERL_SYS_TERM();
a6006777
PP
820 exit(exitstatus);
821 }
822
a6006777
PP
823Now compile:
824
54310121 825 % cc -o persistent persistent.c `perl -MExtUtils::Embed -e ccopts -e ldopts`
a6006777 826
d1be9408 827Here's an example script file:
a6006777
PP
828
829 #test.pl
830 my $string = "hello";
831 foo($string);
832
833 sub foo {
834 print "foo says: @_\n";
835 }
836
837Now run:
838
839 % persistent
840 Enter file name: test.pl
841 foo says: hello
842 Enter file name: test.pl
843 already compiled Embed::test_2epl->handler
844 foo says: hello
845 Enter file name: ^C
846
d95b23b2
AB
847=head2 Execution of END blocks
848
849Traditionally END blocks have been executed at the end of the perl_run.
850This causes problems for applications that never call perl_run. Since
851perl 5.7.2 you can specify C<PL_exit_flags |= PERL_EXIT_DESTRUCT_END>
852to get the new behaviour. This also enables the running of END blocks if
bf9cdc68 853the perl_parse fails and C<perl_destruct> will return the exit value.
d95b23b2 854
8ebc5c01
PP
855=head2 Maintaining multiple interpreter instances
856
8a7dc658
JO
857Some rare applications will need to create more than one interpreter
858during a session. Such an application might sporadically decide to
54310121 859release any resources associated with the interpreter.
8a7dc658
JO
860
861The program must take care to ensure that this takes place I<before>
9bbedd82
JH
862the next interpreter is constructed. By default, when perl is not
863built with any special options, the global variable
9cde0e7f 864C<PL_perl_destruct_level> is set to C<0>, since extra cleaning isn't
9bbedd82
JH
865usually needed when a program only ever creates a single interpreter
866in its entire lifetime.
8a7dc658 867
9cde0e7f 868Setting C<PL_perl_destruct_level> to C<1> makes everything squeaky clean:
8a7dc658 869
8ebc5c01
PP
870 while(1) {
871 ...
9cde0e7f 872 /* reset global variables here with PL_perl_destruct_level = 1 */
bf9cdc68 873 PL_perl_destruct_level = 1;
54310121 874 perl_construct(my_perl);
8ebc5c01
PP
875 ...
876 /* clean and reset _everything_ during perl_destruct */
bf9cdc68 877 PL_perl_destruct_level = 1;
54310121
PP
878 perl_destruct(my_perl);
879 perl_free(my_perl);
8ebc5c01
PP
880 ...
881 /* let's go do it again! */
882 }
883
54310121 884When I<perl_destruct()> is called, the interpreter's syntax parse tree
bf9cdc68
RG
885and symbol tables are cleaned up, and global variables are reset. The
886second assignment to C<PL_perl_destruct_level> is needed because
887perl_construct resets it to C<0>.
8ebc5c01 888
8a7dc658 889Now suppose we have more than one interpreter instance running at the
9bbedd82
JH
890same time. This is feasible, but only if you used the Configure option
891C<-Dusemultiplicity> or the options C<-Dusethreads -Duseithreads> when
bf9cdc68 892building perl. By default, enabling one of these Configure options
9bbedd82 893sets the per-interpreter global variable C<PL_perl_destruct_level> to
bf9cdc68
RG
894C<1>, so that thorough cleaning is automatic and interpreter variables
895are initialized correctly. Even if you don't intend to run two or
896more interpreters at the same time, but to run them sequentially, like
897in the above example, it is recommended to build perl with the
898C<-Dusemultiplicity> option otherwise some interpreter variables may
899not be initialized correctly between consecutive runs and your
900application may crash.
9bbedd82
JH
901
902Using C<-Dusethreads -Duseithreads> rather than C<-Dusemultiplicity>
903is more appropriate if you intend to run multiple interpreters
904concurrently in different threads, because it enables support for
905linking in the thread libraries of your system with the interpreter.
8ebc5c01
PP
906
907Let's give it a try:
908
909
910 #include <EXTERN.h>
8a7dc658 911 #include <perl.h>
8ebc5c01
PP
912
913 /* we're going to embed two interpreters */
914 /* we're going to embed two interpreters */
915
8ebc5c01
PP
916 #define SAY_HELLO "-e", "print qq(Hi, I'm $^X\n)"
917
8ebc5c01
PP
918 int main(int argc, char **argv, char **env)
919 {
1ccffcf5 920 PerlInterpreter *one_perl, *two_perl;
8ebc5c01
PP
921 char *one_args[] = { "one_perl", SAY_HELLO };
922 char *two_args[] = { "two_perl", SAY_HELLO };
923
1ccffcf5
IZ
924 PERL_SYS_INIT3(&argc,&argv,&env);
925 one_perl = perl_alloc();
926 two_perl = perl_alloc();
927
9bbedd82 928 PERL_SET_CONTEXT(one_perl);
8ebc5c01 929 perl_construct(one_perl);
9bbedd82 930 PERL_SET_CONTEXT(two_perl);
8ebc5c01
PP
931 perl_construct(two_perl);
932
9bbedd82 933 PERL_SET_CONTEXT(one_perl);
8ebc5c01 934 perl_parse(one_perl, NULL, 3, one_args, (char **)NULL);
9bbedd82 935 PERL_SET_CONTEXT(two_perl);
8ebc5c01
PP
936 perl_parse(two_perl, NULL, 3, two_args, (char **)NULL);
937
9bbedd82 938 PERL_SET_CONTEXT(one_perl);
8ebc5c01 939 perl_run(one_perl);
9bbedd82 940 PERL_SET_CONTEXT(two_perl);
8ebc5c01
PP
941 perl_run(two_perl);
942
9bbedd82 943 PERL_SET_CONTEXT(one_perl);
8ebc5c01 944 perl_destruct(one_perl);
9bbedd82 945 PERL_SET_CONTEXT(two_perl);
8ebc5c01
PP
946 perl_destruct(two_perl);
947
9bbedd82 948 PERL_SET_CONTEXT(one_perl);
8ebc5c01 949 perl_free(one_perl);
9bbedd82 950 PERL_SET_CONTEXT(two_perl);
8ebc5c01 951 perl_free(two_perl);
1ccffcf5 952 PERL_SYS_TERM();
8ebc5c01
PP
953 }
954
9bbedd82
JH
955Note the calls to PERL_SET_CONTEXT(). These are necessary to initialize
956the global state that tracks which interpreter is the "current" one on
957the particular process or thread that may be running it. It should
958always be used if you have more than one interpreter and are making
959perl API calls on both interpreters in an interleaved fashion.
960
961PERL_SET_CONTEXT(interp) should also be called whenever C<interp> is
962used by a thread that did not create it (using either perl_alloc(), or
963the more esoteric perl_clone()).
8ebc5c01
PP
964
965Compile as usual:
966
967 % cc -o multiplicity multiplicity.c `perl -MExtUtils::Embed -e ccopts -e ldopts`
968
969Run it, Run it:
970
971 % multiplicity
972 Hi, I'm one_perl
973 Hi, I'm two_perl
974
96dbc785
PP
975=head2 Using Perl modules, which themselves use C libraries, from your C program
976
977If you've played with the examples above and tried to embed a script
978that I<use()>s a Perl module (such as I<Socket>) which itself uses a C or C++ library,
979this probably happened:
980
981
982 Can't load module Socket, dynamic loading not available in this perl.
983 (You may need to build a new perl executable which either supports
984 dynamic loading or has the Socket module statically linked into it.)
985
986
987What's wrong?
988
989Your interpreter doesn't know how to communicate with these extensions
990on its own. A little glue will help. Up until now you've been
991calling I<perl_parse()>, handing it NULL for the second argument:
992
993 perl_parse(my_perl, NULL, argc, my_argv, NULL);
994
995That's where the glue code can be inserted to create the initial contact between
996Perl and linked C/C++ routines. Let's take a look some pieces of I<perlmain.c>
997to see how Perl does this:
998
cc7dda15 999 static void xs_init (pTHX);
96dbc785 1000
cc7dda15
GS
1001 EXTERN_C void boot_DynaLoader (pTHX_ CV* cv);
1002 EXTERN_C void boot_Socket (pTHX_ CV* cv);
96dbc785
PP
1003
1004
1005 EXTERN_C void
cc7dda15 1006 xs_init(pTHX)
96dbc785
PP
1007 {
1008 char *file = __FILE__;
1009 /* DynaLoader is a special case */
1010 newXS("DynaLoader::boot_DynaLoader", boot_DynaLoader, file);
1011 newXS("Socket::bootstrap", boot_Socket, file);
1012 }
1013
1014Simply put: for each extension linked with your Perl executable
1015(determined during its initial configuration on your
1016computer or when adding a new extension),
1017a Perl subroutine is created to incorporate the extension's
1018routines. Normally, that subroutine is named
1019I<Module::bootstrap()> and is invoked when you say I<use Module>. In
1020turn, this hooks into an XSUB, I<boot_Module>, which creates a Perl
1021counterpart for each of the extension's XSUBs. Don't worry about this
1022part; leave that to the I<xsubpp> and extension authors. If your
1023extension is dynamically loaded, DynaLoader creates I<Module::bootstrap()>
1024for you on the fly. In fact, if you have a working DynaLoader then there
5f05dabc 1025is rarely any need to link in any other extensions statically.
96dbc785
PP
1026
1027
1028Once you have this code, slap it into the second argument of I<perl_parse()>:
1029
1030
1031 perl_parse(my_perl, xs_init, argc, my_argv, NULL);
1032
1033
1034Then compile:
1035
8a7dc658 1036 % cc -o interp interp.c `perl -MExtUtils::Embed -e ccopts -e ldopts`
96dbc785
PP
1037
1038 % interp
1039 use Socket;
1040 use SomeDynamicallyLoadedModule;
1041
1042 print "Now I can use extensions!\n"'
1043
1044B<ExtUtils::Embed> can also automate writing the I<xs_init> glue code.
1045
8a7dc658 1046 % perl -MExtUtils::Embed -e xsinit -- -o perlxsi.c
96dbc785
PP
1047 % cc -c perlxsi.c `perl -MExtUtils::Embed -e ccopts`
1048 % cc -c interp.c `perl -MExtUtils::Embed -e ccopts`
8a7dc658 1049 % cc -o interp perlxsi.o interp.o `perl -MExtUtils::Embed -e ldopts`
96dbc785 1050
4929bf7b 1051Consult L<perlxs>, L<perlguts>, and L<perlapi> for more details.
96dbc785 1052
13a2d996 1053=head1 Embedding Perl under Win32
53f52f58 1054
cc7dda15
GS
1055In general, all of the source code shown here should work unmodified under
1056Windows.
53f52f58 1057
cc7dda15
GS
1058However, there are some caveats about the command-line examples shown.
1059For starters, backticks won't work under the Win32 native command shell.
53f52f58
DM
1060The ExtUtils::Embed kit on CPAN ships with a script called
1061B<genmake>, which generates a simple makefile to build a program from
e010571f 1062a single C source file. It can be used like this:
53f52f58
DM
1063
1064 C:\ExtUtils-Embed\eg> perl genmake interp.c
1065 C:\ExtUtils-Embed\eg> nmake
1066 C:\ExtUtils-Embed\eg> interp -e "print qq{I'm embedded in Win32!\n}"
1067
e010571f
GS
1068You may wish to use a more robust environment such as the Microsoft
1069Developer Studio. In this case, run this to generate perlxsi.c:
53f52f58
DM
1070
1071 perl -MExtUtils::Embed -e xsinit
1072
e010571f
GS
1073Create a new project and Insert -> Files into Project: perlxsi.c,
1074perl.lib, and your own source files, e.g. interp.c. Typically you'll
1075find perl.lib in B<C:\perl\lib\CORE>, if not, you should see the
1076B<CORE> directory relative to C<perl -V:archlib>. The studio will
1077also need this path so it knows where to find Perl include files.
1078This path can be added via the Tools -> Options -> Directories menu.
1079Finally, select Build -> Build interp.exe and you're ready to go.
96dbc785 1080
35209cc8
JH
1081=head1 Hiding Perl_
1082
1083If you completely hide the short forms forms of the Perl public API,
d51482e4 1084add -DPERL_NO_SHORT_NAMES to the compilation flags. This means that
35209cc8
JH
1085for example instead of writing
1086
1087 warn("%d bottles of beer on the wall", bottlecount);
1088
1089you will have to write the explicit full form
1090
1091 Perl_warn(aTHX_ "%d bottles of beer on the wall", bottlecount);
1092
1093(See L<perlguts/Background and PERL_IMPLICIT_CONTEXT for the explanation
1094of the C<aTHX_>.> ) Hiding the short forms is very useful for avoiding
1095all sorts of nasty (C preprocessor or otherwise) conflicts with other
1096software packages (Perl defines about 2400 APIs with these short names,
1097take or leave few hundred, so there certainly is room for conflict.)
1098
cb1a09d0
AD
1099=head1 MORAL
1100
1101You can sometimes I<write faster code> in C, but
5f05dabc 1102you can always I<write code faster> in Perl. Because you can use
cb1a09d0
AD
1103each from the other, combine them as you wish.
1104
1105
1106=head1 AUTHOR
1107
8eabb633
JH
1108Jon Orwant <F<orwant@media.mit.edu>> and Doug MacEachern
1109<F<dougm@covalent.net>>, with small contributions from Tim Bunce, Tom
e010571f
GS
1110Christiansen, Guy Decoux, Hallvard Furuseth, Dov Grobgeld, and Ilya
1111Zakharevich.
cb1a09d0 1112
e010571f 1113Doug MacEachern has an article on embedding in Volume 1, Issue 4 of
f224927c 1114The Perl Journal ( http://www.tpj.com/ ). Doug is also the developer of the
e010571f
GS
1115most widely-used Perl embedding: the mod_perl system
1116(perl.apache.org), which embeds Perl in the Apache web server.
1117Oracle, Binary Evolution, ActiveState, and Ben Sugars's nsapi_perl
1118have used this model for Oracle, Netscape and Internet Information
1119Server Perl plugins.
cb1a09d0 1120
8a7dc658
JO
1121=head1 COPYRIGHT
1122
e010571f 1123Copyright (C) 1995, 1996, 1997, 1998 Doug MacEachern and Jon Orwant. All
8a7dc658
JO
1124Rights Reserved.
1125
e010571f
GS
1126Permission is granted to make and distribute verbatim copies of this
1127documentation provided the copyright notice and this permission notice are
1128preserved on all copies.
1129
1130Permission is granted to copy and distribute modified versions of this
1131documentation under the conditions for verbatim copying, provided also
1132that they are marked clearly as modified versions, that the authors'
1133names and title are unchanged (though subtitles and additional
1134authors' names may be added), and that the entire resulting derived
1135work is distributed under the terms of a permission notice identical
1136to this one.
1137
1138Permission is granted to copy and distribute translations of this
1139documentation into another language, under the above conditions for
1140modified versions.