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