Commit | Line | Data |
---|---|---|
920dae64 AT |
1 | .\" Automatically generated by Pod::Man v1.37, Pod::Parser v1.32 |
2 | .\" | |
3 | .\" Standard preamble: | |
4 | .\" ======================================================================== | |
5 | .de Sh \" Subsection heading | |
6 | .br | |
7 | .if t .Sp | |
8 | .ne 5 | |
9 | .PP | |
10 | \fB\\$1\fR | |
11 | .PP | |
12 | .. | |
13 | .de Sp \" Vertical space (when we can't use .PP) | |
14 | .if t .sp .5v | |
15 | .if n .sp | |
16 | .. | |
17 | .de Vb \" Begin verbatim text | |
18 | .ft CW | |
19 | .nf | |
20 | .ne \\$1 | |
21 | .. | |
22 | .de Ve \" End verbatim text | |
23 | .ft R | |
24 | .fi | |
25 | .. | |
26 | .\" Set up some character translations and predefined strings. \*(-- will | |
27 | .\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left | |
28 | .\" double quote, and \*(R" will give a right double quote. | will give a | |
29 | .\" real vertical bar. \*(C+ will give a nicer C++. Capital omega is used to | |
30 | .\" do unbreakable dashes and therefore won't be available. \*(C` and \*(C' | |
31 | .\" expand to `' in nroff, nothing in troff, for use with C<>. | |
32 | .tr \(*W-|\(bv\*(Tr | |
33 | .ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p' | |
34 | .ie n \{\ | |
35 | . ds -- \(*W- | |
36 | . ds PI pi | |
37 | . if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch | |
38 | . if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\" diablo 12 pitch | |
39 | . ds L" "" | |
40 | . ds R" "" | |
41 | . ds C` "" | |
42 | . ds C' "" | |
43 | 'br\} | |
44 | .el\{\ | |
45 | . ds -- \|\(em\| | |
46 | . ds PI \(*p | |
47 | . ds L" `` | |
48 | . ds R" '' | |
49 | 'br\} | |
50 | .\" | |
51 | .\" If the F register is turned on, we'll generate index entries on stderr for | |
52 | .\" titles (.TH), headers (.SH), subsections (.Sh), items (.Ip), and index | |
53 | .\" entries marked with X<> in POD. Of course, you'll have to process the | |
54 | .\" output yourself in some meaningful fashion. | |
55 | .if \nF \{\ | |
56 | . de IX | |
57 | . tm Index:\\$1\t\\n%\t"\\$2" | |
58 | .. | |
59 | . nr % 0 | |
60 | . rr F | |
61 | .\} | |
62 | .\" | |
63 | .\" For nroff, turn off justification. Always turn off hyphenation; it makes | |
64 | .\" way too many mistakes in technical documents. | |
65 | .hy 0 | |
66 | .if n .na | |
67 | .\" | |
68 | .\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2). | |
69 | .\" Fear. Run. Save yourself. No user-serviceable parts. | |
70 | . \" fudge factors for nroff and troff | |
71 | .if n \{\ | |
72 | . ds #H 0 | |
73 | . ds #V .8m | |
74 | . ds #F .3m | |
75 | . ds #[ \f1 | |
76 | . ds #] \fP | |
77 | .\} | |
78 | .if t \{\ | |
79 | . ds #H ((1u-(\\\\n(.fu%2u))*.13m) | |
80 | . ds #V .6m | |
81 | . ds #F 0 | |
82 | . ds #[ \& | |
83 | . ds #] \& | |
84 | .\} | |
85 | . \" simple accents for nroff and troff | |
86 | .if n \{\ | |
87 | . ds ' \& | |
88 | . ds ` \& | |
89 | . ds ^ \& | |
90 | . ds , \& | |
91 | . ds ~ ~ | |
92 | . ds / | |
93 | .\} | |
94 | .if t \{\ | |
95 | . ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u" | |
96 | . ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u' | |
97 | . ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u' | |
98 | . ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u' | |
99 | . ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u' | |
100 | . ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u' | |
101 | .\} | |
102 | . \" troff and (daisy-wheel) nroff accents | |
103 | .ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V' | |
104 | .ds 8 \h'\*(#H'\(*b\h'-\*(#H' | |
105 | .ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#] | |
106 | .ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H' | |
107 | .ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u' | |
108 | .ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#] | |
109 | .ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#] | |
110 | .ds ae a\h'-(\w'a'u*4/10)'e | |
111 | .ds Ae A\h'-(\w'A'u*4/10)'E | |
112 | . \" corrections for vroff | |
113 | .if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u' | |
114 | .if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u' | |
115 | . \" for low resolution devices (crt and lpr) | |
116 | .if \n(.H>23 .if \n(.V>19 \ | |
117 | \{\ | |
118 | . ds : e | |
119 | . ds 8 ss | |
120 | . ds o a | |
121 | . ds d- d\h'-1'\(ga | |
122 | . ds D- D\h'-1'\(hy | |
123 | . ds th \o'bp' | |
124 | . ds Th \o'LP' | |
125 | . ds ae ae | |
126 | . ds Ae AE | |
127 | .\} | |
128 | .rm #[ #] #H #V #F C | |
129 | .\" ======================================================================== | |
130 | .\" | |
131 | .IX Title "PERLEMBED 1" | |
132 | .TH PERLEMBED 1 "2006-01-07" "perl v5.8.8" "Perl Programmers Reference Guide" | |
133 | .SH "NAME" | |
134 | perlembed \- how to embed perl in your C program | |
135 | .SH "DESCRIPTION" | |
136 | .IX Header "DESCRIPTION" | |
137 | .Sh "\s-1PREAMBLE\s0" | |
138 | .IX Subsection "PREAMBLE" | |
139 | Do you want to: | |
140 | .IP "\fBUse C from Perl?\fR" 5 | |
141 | .IX Item "Use C from Perl?" | |
142 | Read perlxstut, perlxs, h2xs, perlguts, and perlapi. | |
143 | .IP "\fBUse a Unix program from Perl?\fR" 5 | |
144 | .IX Item "Use a Unix program from Perl?" | |
145 | Read about back-quotes and about \f(CW\*(C`system\*(C'\fR and \f(CW\*(C`exec\*(C'\fR in perlfunc. | |
146 | .IP "\fBUse Perl from Perl?\fR" 5 | |
147 | .IX Item "Use Perl from Perl?" | |
148 | Read about \*(L"do\*(R" in perlfunc and \*(L"eval\*(R" in perlfunc and \*(L"require\*(R" in perlfunc | |
149 | and \*(L"use\*(R" in perlfunc. | |
150 | .IP "\fBUse C from C?\fR" 5 | |
151 | .IX Item "Use C from C?" | |
152 | Rethink your design. | |
153 | .IP "\fBUse Perl from C?\fR" 5 | |
154 | .IX Item "Use Perl from C?" | |
155 | Read on... | |
156 | .Sh "\s-1ROADMAP\s0" | |
157 | .IX Subsection "ROADMAP" | |
158 | .IP "\(bu" 5 | |
159 | Compiling your C program | |
160 | .IP "\(bu" 5 | |
161 | Adding a Perl interpreter to your C program | |
162 | .IP "\(bu" 5 | |
163 | Calling a Perl subroutine from your C program | |
164 | .IP "\(bu" 5 | |
165 | Evaluating a Perl statement from your C program | |
166 | .IP "\(bu" 5 | |
167 | Performing Perl pattern matches and substitutions from your C program | |
168 | .IP "\(bu" 5 | |
169 | Fiddling with the Perl stack from your C program | |
170 | .IP "\(bu" 5 | |
171 | Maintaining a persistent interpreter | |
172 | .IP "\(bu" 5 | |
173 | Maintaining multiple interpreter instances | |
174 | .IP "\(bu" 5 | |
175 | Using Perl modules, which themselves use C libraries, from your C program | |
176 | .IP "\(bu" 5 | |
177 | Embedding Perl under Win32 | |
178 | .Sh "Compiling your C program" | |
179 | .IX Subsection "Compiling your C program" | |
180 | If you have trouble compiling the scripts in this documentation, | |
181 | you're not alone. The cardinal rule: \s-1COMPILE\s0 \s-1THE\s0 \s-1PROGRAMS\s0 \s-1IN\s0 \s-1EXACTLY\s0 | |
182 | \&\s-1THE\s0 \s-1SAME\s0 \s-1WAY\s0 \s-1THAT\s0 \s-1YOUR\s0 \s-1PERL\s0 \s-1WAS\s0 \s-1COMPILED\s0. (Sorry for yelling.) | |
183 | .PP | |
184 | Also, every C program that uses Perl must link in the \fIperl library\fR. | |
185 | What's that, you ask? Perl is itself written in C; the perl library | |
186 | is the collection of compiled C programs that were used to create your | |
187 | perl executable (\fI/usr/bin/perl\fR or equivalent). (Corollary: you | |
188 | can't use Perl from your C program unless Perl has been compiled on | |
189 | your machine, or installed properly\*(--that's why you shouldn't blithely | |
190 | copy Perl executables from machine to machine without also copying the | |
191 | \&\fIlib\fR directory.) | |
192 | .PP | |
193 | When you use Perl from C, your C program will\*(--usually\-\-allocate, | |
194 | \&\*(L"run\*(R", and deallocate a \fIPerlInterpreter\fR object, which is defined by | |
195 | the perl library. | |
196 | .PP | |
197 | If your copy of Perl is recent enough to contain this documentation | |
198 | (version 5.002 or later), then the perl library (and \fI\s-1EXTERN\s0.h\fR and | |
199 | \&\fIperl.h\fR, which you'll also need) will reside in a directory | |
200 | that looks like this: | |
201 | .PP | |
202 | .Vb 1 | |
203 | \& /usr/local/lib/perl5/your_architecture_here/CORE | |
204 | .Ve | |
205 | .PP | |
206 | or perhaps just | |
207 | .PP | |
208 | .Vb 1 | |
209 | \& /usr/local/lib/perl5/CORE | |
210 | .Ve | |
211 | .PP | |
212 | or maybe something like | |
213 | .PP | |
214 | .Vb 1 | |
215 | \& /usr/opt/perl5/CORE | |
216 | .Ve | |
217 | .PP | |
218 | Execute this statement for a hint about where to find \s-1CORE:\s0 | |
219 | .PP | |
220 | .Vb 1 | |
221 | \& perl -MConfig -e 'print $Config{archlib}' | |
222 | .Ve | |
223 | .PP | |
224 | Here's how you'd compile the example in the next section, | |
225 | \&\*(L"Adding a Perl interpreter to your C program\*(R", on my Linux box: | |
226 | .PP | |
227 | .Vb 4 | |
228 | \& % gcc -O2 -Dbool=char -DHAS_BOOL -I/usr/local/include | |
229 | \& -I/usr/local/lib/perl5/i586-linux/5.003/CORE | |
230 | \& -L/usr/local/lib/perl5/i586-linux/5.003/CORE | |
231 | \& -o interp interp.c -lperl -lm | |
232 | .Ve | |
233 | .PP | |
234 | (That's all one line.) On my \s-1DEC\s0 Alpha running old 5.003_05, the | |
235 | incantation is a bit different: | |
236 | .PP | |
237 | .Vb 4 | |
238 | \& % cc -O2 -Olimit 2900 -DSTANDARD_C -I/usr/local/include | |
239 | \& -I/usr/local/lib/perl5/alpha-dec_osf/5.00305/CORE | |
240 | \& -L/usr/local/lib/perl5/alpha-dec_osf/5.00305/CORE -L/usr/local/lib | |
241 | \& -D__LANGUAGE_C__ -D_NO_PROTO -o interp interp.c -lperl -lm | |
242 | .Ve | |
243 | .PP | |
244 | How can you figure out what to add? Assuming your Perl is post\-5.001, | |
245 | execute a \f(CW\*(C`perl \-V\*(C'\fR command and pay special attention to the \*(L"cc\*(R" and | |
246 | \&\*(L"ccflags\*(R" information. | |
247 | .PP | |
248 | You'll have to choose the appropriate compiler (\fIcc\fR, \fIgcc\fR, et al.) for | |
249 | your machine: \f(CW\*(C`perl \-MConfig \-e 'print $Config{cc}'\*(C'\fR will tell you what | |
250 | to use. | |
251 | .PP | |
252 | You'll also have to choose the appropriate library directory | |
253 | (\fI/usr/local/lib/...\fR) for your machine. If your compiler complains | |
254 | that certain functions are undefined, or that it can't locate | |
255 | \&\fI\-lperl\fR, then you need to change the path following the \f(CW\*(C`\-L\*(C'\fR. If it | |
256 | complains that it can't find \fI\s-1EXTERN\s0.h\fR and \fIperl.h\fR, you need to | |
257 | change the path following the \f(CW\*(C`\-I\*(C'\fR. | |
258 | .PP | |
259 | You may have to add extra libraries as well. Which ones? | |
260 | Perhaps those printed by | |
261 | .PP | |
262 | .Vb 1 | |
263 | \& perl -MConfig -e 'print $Config{libs}' | |
264 | .Ve | |
265 | .PP | |
266 | Provided your perl binary was properly configured and installed the | |
267 | \&\fBExtUtils::Embed\fR module will determine all of this information for | |
268 | you: | |
269 | .PP | |
270 | .Vb 1 | |
271 | \& % cc -o interp interp.c `perl -MExtUtils::Embed -e ccopts -e ldopts` | |
272 | .Ve | |
273 | .PP | |
274 | If the \fBExtUtils::Embed\fR module isn't part of your Perl distribution, | |
275 | you can retrieve it from | |
276 | http://www.perl.com/perl/CPAN/modules/by\-module/ExtUtils/ | |
277 | (If this documentation came from your Perl distribution, then you're | |
278 | running 5.004 or better and you already have it.) | |
279 | .PP | |
280 | The \fBExtUtils::Embed\fR kit on \s-1CPAN\s0 also contains all source code for | |
281 | the examples in this document, tests, additional examples and other | |
282 | information you may find useful. | |
283 | .Sh "Adding a Perl interpreter to your C program" | |
284 | .IX Subsection "Adding a Perl interpreter to your C program" | |
285 | In a sense, perl (the C program) is a good example of embedding Perl | |
286 | (the language), so I'll demonstrate embedding with \fIminiperlmain.c\fR, | |
287 | included in the source distribution. Here's a bastardized, nonportable | |
288 | version of \fIminiperlmain.c\fR containing the essentials of embedding: | |
289 | .PP | |
290 | .Vb 2 | |
291 | \& #include <EXTERN.h> /* from the Perl distribution */ | |
292 | \& #include <perl.h> /* from the Perl distribution */ | |
293 | .Ve | |
294 | .PP | |
295 | .Vb 1 | |
296 | \& static PerlInterpreter *my_perl; /*** The Perl interpreter ***/ | |
297 | .Ve | |
298 | .PP | |
299 | .Vb 12 | |
300 | \& int main(int argc, char **argv, char **env) | |
301 | \& { | |
302 | \& PERL_SYS_INIT3(&argc,&argv,&env); | |
303 | \& my_perl = perl_alloc(); | |
304 | \& perl_construct(my_perl); | |
305 | \& PL_exit_flags |= PERL_EXIT_DESTRUCT_END; | |
306 | \& perl_parse(my_perl, NULL, argc, argv, (char **)NULL); | |
307 | \& perl_run(my_perl); | |
308 | \& perl_destruct(my_perl); | |
309 | \& perl_free(my_perl); | |
310 | \& PERL_SYS_TERM(); | |
311 | \& } | |
312 | .Ve | |
313 | .PP | |
314 | Notice that we don't use the \f(CW\*(C`env\*(C'\fR pointer. Normally handed to | |
315 | \&\f(CW\*(C`perl_parse\*(C'\fR as its final argument, \f(CW\*(C`env\*(C'\fR here is replaced by | |
316 | \&\f(CW\*(C`NULL\*(C'\fR, which means that the current environment will be used. The macros | |
317 | \&\s-1\fIPERL_SYS_INIT3\s0()\fR and \s-1\fIPERL_SYS_TERM\s0()\fR provide system-specific tune up | |
318 | of the C runtime environment necessary to run Perl interpreters; since | |
319 | \&\s-1\fIPERL_SYS_INIT3\s0()\fR may change \f(CW\*(C`env\*(C'\fR, it may be more appropriate to provide | |
320 | \&\f(CW\*(C`env\*(C'\fR as an argument to \fIperl_parse()\fR. | |
321 | .PP | |
322 | Now compile this program (I'll call it \fIinterp.c\fR) into an executable: | |
323 | .PP | |
324 | .Vb 1 | |
325 | \& % cc -o interp interp.c `perl -MExtUtils::Embed -e ccopts -e ldopts` | |
326 | .Ve | |
327 | .PP | |
328 | After a successful compilation, you'll be able to use \fIinterp\fR just | |
329 | like perl itself: | |
330 | .PP | |
331 | .Vb 6 | |
332 | \& % interp | |
333 | \& print "Pretty Good Perl \en"; | |
334 | \& print "10890 - 9801 is ", 10890 - 9801; | |
335 | \& <CTRL-D> | |
336 | \& Pretty Good Perl | |
337 | \& 10890 - 9801 is 1089 | |
338 | .Ve | |
339 | .PP | |
340 | or | |
341 | .PP | |
342 | .Vb 2 | |
343 | \& % interp -e 'printf("%x", 3735928559)' | |
344 | \& deadbeef | |
345 | .Ve | |
346 | .PP | |
347 | You can also read and execute Perl statements from a file while in the | |
348 | midst of your C program, by placing the filename in \fIargv[1]\fR before | |
349 | calling \fIperl_run\fR. | |
350 | .Sh "Calling a Perl subroutine from your C program" | |
351 | .IX Subsection "Calling a Perl subroutine from your C program" | |
352 | To call individual Perl subroutines, you can use any of the \fBcall_*\fR | |
353 | functions documented in perlcall. | |
354 | In this example we'll use \f(CW\*(C`call_argv\*(C'\fR. | |
355 | .PP | |
356 | That's shown below, in a program I'll call \fIshowtime.c\fR. | |
357 | .PP | |
358 | .Vb 2 | |
359 | \& #include <EXTERN.h> | |
360 | \& #include <perl.h> | |
361 | .Ve | |
362 | .PP | |
363 | .Vb 1 | |
364 | \& static PerlInterpreter *my_perl; | |
365 | .Ve | |
366 | .PP | |
367 | .Vb 6 | |
368 | \& int main(int argc, char **argv, char **env) | |
369 | \& { | |
370 | \& char *args[] = { NULL }; | |
371 | \& PERL_SYS_INIT3(&argc,&argv,&env); | |
372 | \& my_perl = perl_alloc(); | |
373 | \& perl_construct(my_perl); | |
374 | .Ve | |
375 | .PP | |
376 | .Vb 2 | |
377 | \& perl_parse(my_perl, NULL, argc, argv, NULL); | |
378 | \& PL_exit_flags |= PERL_EXIT_DESTRUCT_END; | |
379 | .Ve | |
380 | .PP | |
381 | .Vb 1 | |
382 | \& /*** skipping perl_run() ***/ | |
383 | .Ve | |
384 | .PP | |
385 | .Vb 1 | |
386 | \& call_argv("showtime", G_DISCARD | G_NOARGS, args); | |
387 | .Ve | |
388 | .PP | |
389 | .Vb 4 | |
390 | \& perl_destruct(my_perl); | |
391 | \& perl_free(my_perl); | |
392 | \& PERL_SYS_TERM(); | |
393 | \& } | |
394 | .Ve | |
395 | .PP | |
396 | where \fIshowtime\fR is a Perl subroutine that takes no arguments (that's the | |
397 | \&\fIG_NOARGS\fR) and for which I'll ignore the return value (that's the | |
398 | \&\fIG_DISCARD\fR). Those flags, and others, are discussed in perlcall. | |
399 | .PP | |
400 | I'll define the \fIshowtime\fR subroutine in a file called \fIshowtime.pl\fR: | |
401 | .PP | |
402 | .Vb 1 | |
403 | \& print "I shan't be printed."; | |
404 | .Ve | |
405 | .PP | |
406 | .Vb 3 | |
407 | \& sub showtime { | |
408 | \& print time; | |
409 | \& } | |
410 | .Ve | |
411 | .PP | |
412 | Simple enough. Now compile and run: | |
413 | .PP | |
414 | .Vb 1 | |
415 | \& % cc -o showtime showtime.c `perl -MExtUtils::Embed -e ccopts -e ldopts` | |
416 | .Ve | |
417 | .PP | |
418 | .Vb 2 | |
419 | \& % showtime showtime.pl | |
420 | \& 818284590 | |
421 | .Ve | |
422 | .PP | |
423 | yielding the number of seconds that elapsed between January 1, 1970 | |
424 | (the beginning of the Unix epoch), and the moment I began writing this | |
425 | sentence. | |
426 | .PP | |
427 | In this particular case we don't have to call \fIperl_run\fR, as we set | |
428 | the PL_exit_flag \s-1PERL_EXIT_DESTRUCT_END\s0 which executes \s-1END\s0 blocks in | |
429 | perl_destruct. | |
430 | .PP | |
431 | If you want to pass arguments to the Perl subroutine, you can add | |
432 | strings to the \f(CW\*(C`NULL\*(C'\fR\-terminated \f(CW\*(C`args\*(C'\fR list passed to | |
433 | \&\fIcall_argv\fR. For other data types, or to examine return values, | |
434 | you'll need to manipulate the Perl stack. That's demonstrated in | |
435 | \&\*(L"Fiddling with the Perl stack from your C program\*(R". | |
436 | .Sh "Evaluating a Perl statement from your C program" | |
437 | .IX Subsection "Evaluating a Perl statement from your C program" | |
438 | Perl provides two \s-1API\s0 functions to evaluate pieces of Perl code. | |
439 | These are \*(L"eval_sv\*(R" in perlapi and \*(L"eval_pv\*(R" in perlapi. | |
440 | .PP | |
441 | Arguably, these are the only routines you'll ever need to execute | |
442 | snippets of Perl code from within your C program. Your code can be as | |
443 | long as you wish; it can contain multiple statements; it can employ | |
444 | \&\*(L"use\*(R" in perlfunc, \*(L"require\*(R" in perlfunc, and \*(L"do\*(R" in perlfunc to | |
445 | include external Perl files. | |
446 | .PP | |
447 | \&\fIeval_pv\fR lets us evaluate individual Perl strings, and then | |
448 | extract variables for coercion into C types. The following program, | |
449 | \&\fIstring.c\fR, executes three Perl strings, extracting an \f(CW\*(C`int\*(C'\fR from | |
450 | the first, a \f(CW\*(C`float\*(C'\fR from the second, and a \f(CW\*(C`char *\*(C'\fR from the third. | |
451 | .PP | |
452 | .Vb 2 | |
453 | \& #include <EXTERN.h> | |
454 | \& #include <perl.h> | |
455 | .Ve | |
456 | .PP | |
457 | .Vb 1 | |
458 | \& static PerlInterpreter *my_perl; | |
459 | .Ve | |
460 | .PP | |
461 | .Vb 4 | |
462 | \& main (int argc, char **argv, char **env) | |
463 | \& { | |
464 | \& STRLEN n_a; | |
465 | \& char *embedding[] = { "", "-e", "0" }; | |
466 | .Ve | |
467 | .PP | |
468 | .Vb 3 | |
469 | \& PERL_SYS_INIT3(&argc,&argv,&env); | |
470 | \& my_perl = perl_alloc(); | |
471 | \& perl_construct( my_perl ); | |
472 | .Ve | |
473 | .PP | |
474 | .Vb 3 | |
475 | \& perl_parse(my_perl, NULL, 3, embedding, NULL); | |
476 | \& PL_exit_flags |= PERL_EXIT_DESTRUCT_END; | |
477 | \& perl_run(my_perl); | |
478 | .Ve | |
479 | .PP | |
480 | .Vb 3 | |
481 | \& /** Treat $a as an integer **/ | |
482 | \& eval_pv("$a = 3; $a **= 2", TRUE); | |
483 | \& printf("a = %d\en", SvIV(get_sv("a", FALSE))); | |
484 | .Ve | |
485 | .PP | |
486 | .Vb 3 | |
487 | \& /** Treat $a as a float **/ | |
488 | \& eval_pv("$a = 3.14; $a **= 2", TRUE); | |
489 | \& printf("a = %f\en", SvNV(get_sv("a", FALSE))); | |
490 | .Ve | |
491 | .PP | |
492 | .Vb 3 | |
493 | \& /** Treat $a as a string **/ | |
494 | \& eval_pv("$a = 'rekcaH lreP rehtonA tsuJ'; $a = reverse($a);", TRUE); | |
495 | \& printf("a = %s\en", SvPV(get_sv("a", FALSE), n_a)); | |
496 | .Ve | |
497 | .PP | |
498 | .Vb 4 | |
499 | \& perl_destruct(my_perl); | |
500 | \& perl_free(my_perl); | |
501 | \& PERL_SYS_TERM(); | |
502 | \& } | |
503 | .Ve | |
504 | .PP | |
505 | All of those strange functions with \fIsv\fR in their names help convert Perl scalars to C types. They're described in perlguts and perlapi. | |
506 | .PP | |
507 | If you compile and run \fIstring.c\fR, you'll see the results of using | |
508 | \&\fI\fISvIV()\fI\fR to create an \f(CW\*(C`int\*(C'\fR, \fI\fISvNV()\fI\fR to create a \f(CW\*(C`float\*(C'\fR, and | |
509 | \&\fI\fISvPV()\fI\fR to create a string: | |
510 | .PP | |
511 | .Vb 3 | |
512 | \& a = 9 | |
513 | \& a = 9.859600 | |
514 | \& a = Just Another Perl Hacker | |
515 | .Ve | |
516 | .PP | |
517 | In the example above, we've created a global variable to temporarily | |
518 | store the computed value of our eval'd expression. It is also | |
519 | possible and in most cases a better strategy to fetch the return value | |
520 | from \fI\fIeval_pv()\fI\fR instead. Example: | |
521 | .PP | |
522 | .Vb 5 | |
523 | \& ... | |
524 | \& STRLEN n_a; | |
525 | \& SV *val = eval_pv("reverse 'rekcaH lreP rehtonA tsuJ'", TRUE); | |
526 | \& printf("%s\en", SvPV(val,n_a)); | |
527 | \& ... | |
528 | .Ve | |
529 | .PP | |
530 | This way, we avoid namespace pollution by not creating global | |
531 | variables and we've simplified our code as well. | |
532 | .Sh "Performing Perl pattern matches and substitutions from your C program" | |
533 | .IX Subsection "Performing Perl pattern matches and substitutions from your C program" | |
534 | The \fI\fIeval_sv()\fI\fR function lets us evaluate strings of Perl code, so we can | |
535 | define some functions that use it to \*(L"specialize\*(R" in matches and | |
536 | substitutions: \fI\fImatch()\fI\fR, \fI\fIsubstitute()\fI\fR, and \fI\fImatches()\fI\fR. | |
537 | .PP | |
538 | .Vb 1 | |
539 | \& I32 match(SV *string, char *pattern); | |
540 | .Ve | |
541 | .PP | |
542 | Given a string and a pattern (e.g., \f(CW\*(C`m/clasp/\*(C'\fR or \f(CW\*(C`/\eb\ew*\eb/\*(C'\fR, which | |
543 | in your C program might appear as \*(L"/\e\eb\e\ew*\e\eb/\*(R"), \fImatch()\fR | |
544 | returns 1 if the string matches the pattern and 0 otherwise. | |
545 | .PP | |
546 | .Vb 1 | |
547 | \& int substitute(SV **string, char *pattern); | |
548 | .Ve | |
549 | .PP | |
550 | Given a pointer to an \f(CW\*(C`SV\*(C'\fR and an \f(CW\*(C`=~\*(C'\fR operation (e.g., | |
551 | \&\f(CW\*(C`s/bob/robert/g\*(C'\fR or \f(CW\*(C`tr[A\-Z][a\-z]\*(C'\fR), \fIsubstitute()\fR modifies the string | |
552 | within the \f(CW\*(C`SV\*(C'\fR as according to the operation, returning the number of substitutions | |
553 | made. | |
554 | .PP | |
555 | .Vb 1 | |
556 | \& int matches(SV *string, char *pattern, AV **matches); | |
557 | .Ve | |
558 | .PP | |
559 | Given an \f(CW\*(C`SV\*(C'\fR, a pattern, and a pointer to an empty \f(CW\*(C`AV\*(C'\fR, | |
560 | \&\fImatches()\fR evaluates \f(CW\*(C`$string =~ $pattern\*(C'\fR in a list context, and | |
561 | fills in \fImatches\fR with the array elements, returning the number of matches found. | |
562 | .PP | |
563 | Here's a sample program, \fImatch.c\fR, that uses all three (long lines have | |
564 | been wrapped here): | |
565 | .PP | |
566 | .Vb 2 | |
567 | \& #include <EXTERN.h> | |
568 | \& #include <perl.h> | |
569 | .Ve | |
570 | .PP | |
571 | .Vb 1 | |
572 | \& static PerlInterpreter *my_perl; | |
573 | .Ve | |
574 | .PP | |
575 | .Vb 9 | |
576 | \& /** my_eval_sv(code, error_check) | |
577 | \& ** kinda like eval_sv(), | |
578 | \& ** but we pop the return value off the stack | |
579 | \& **/ | |
580 | \& SV* my_eval_sv(SV *sv, I32 croak_on_error) | |
581 | \& { | |
582 | \& dSP; | |
583 | \& SV* retval; | |
584 | \& STRLEN n_a; | |
585 | .Ve | |
586 | .PP | |
587 | .Vb 2 | |
588 | \& PUSHMARK(SP); | |
589 | \& eval_sv(sv, G_SCALAR); | |
590 | .Ve | |
591 | .PP | |
592 | .Vb 3 | |
593 | \& SPAGAIN; | |
594 | \& retval = POPs; | |
595 | \& PUTBACK; | |
596 | .Ve | |
597 | .PP | |
598 | .Vb 2 | |
599 | \& if (croak_on_error && SvTRUE(ERRSV)) | |
600 | \& croak(SvPVx(ERRSV, n_a)); | |
601 | .Ve | |
602 | .PP | |
603 | .Vb 2 | |
604 | \& return retval; | |
605 | \& } | |
606 | .Ve | |
607 | .PP | |
608 | .Vb 6 | |
609 | \& /** match(string, pattern) | |
610 | \& ** | |
611 | \& ** Used for matches in a scalar context. | |
612 | \& ** | |
613 | \& ** Returns 1 if the match was successful; 0 otherwise. | |
614 | \& **/ | |
615 | .Ve | |
616 | .PP | |
617 | .Vb 4 | |
618 | \& I32 match(SV *string, char *pattern) | |
619 | \& { | |
620 | \& SV *command = NEWSV(1099, 0), *retval; | |
621 | \& STRLEN n_a; | |
622 | .Ve | |
623 | .PP | |
624 | .Vb 2 | |
625 | \& sv_setpvf(command, "my $string = '%s'; $string =~ %s", | |
626 | \& SvPV(string,n_a), pattern); | |
627 | .Ve | |
628 | .PP | |
629 | .Vb 2 | |
630 | \& retval = my_eval_sv(command, TRUE); | |
631 | \& SvREFCNT_dec(command); | |
632 | .Ve | |
633 | .PP | |
634 | .Vb 2 | |
635 | \& return SvIV(retval); | |
636 | \& } | |
637 | .Ve | |
638 | .PP | |
639 | .Vb 7 | |
640 | \& /** substitute(string, pattern) | |
641 | \& ** | |
642 | \& ** Used for =~ operations that modify their left-hand side (s/// and tr///) | |
643 | \& ** | |
644 | \& ** Returns the number of successful matches, and | |
645 | \& ** modifies the input string if there were any. | |
646 | \& **/ | |
647 | .Ve | |
648 | .PP | |
649 | .Vb 4 | |
650 | \& I32 substitute(SV **string, char *pattern) | |
651 | \& { | |
652 | \& SV *command = NEWSV(1099, 0), *retval; | |
653 | \& STRLEN n_a; | |
654 | .Ve | |
655 | .PP | |
656 | .Vb 2 | |
657 | \& sv_setpvf(command, "$string = '%s'; ($string =~ %s)", | |
658 | \& SvPV(*string,n_a), pattern); | |
659 | .Ve | |
660 | .PP | |
661 | .Vb 2 | |
662 | \& retval = my_eval_sv(command, TRUE); | |
663 | \& SvREFCNT_dec(command); | |
664 | .Ve | |
665 | .PP | |
666 | .Vb 3 | |
667 | \& *string = get_sv("string", FALSE); | |
668 | \& return SvIV(retval); | |
669 | \& } | |
670 | .Ve | |
671 | .PP | |
672 | .Vb 7 | |
673 | \& /** matches(string, pattern, matches) | |
674 | \& ** | |
675 | \& ** Used for matches in a list context. | |
676 | \& ** | |
677 | \& ** Returns the number of matches, | |
678 | \& ** and fills in **matches with the matching substrings | |
679 | \& **/ | |
680 | .Ve | |
681 | .PP | |
682 | .Vb 5 | |
683 | \& I32 matches(SV *string, char *pattern, AV **match_list) | |
684 | \& { | |
685 | \& SV *command = NEWSV(1099, 0); | |
686 | \& I32 num_matches; | |
687 | \& STRLEN n_a; | |
688 | .Ve | |
689 | .PP | |
690 | .Vb 2 | |
691 | \& sv_setpvf(command, "my $string = '%s'; @array = ($string =~ %s)", | |
692 | \& SvPV(string,n_a), pattern); | |
693 | .Ve | |
694 | .PP | |
695 | .Vb 2 | |
696 | \& my_eval_sv(command, TRUE); | |
697 | \& SvREFCNT_dec(command); | |
698 | .Ve | |
699 | .PP | |
700 | .Vb 2 | |
701 | \& *match_list = get_av("array", FALSE); | |
702 | \& num_matches = av_len(*match_list) + 1; /** assume $[ is 0 **/ | |
703 | .Ve | |
704 | .PP | |
705 | .Vb 2 | |
706 | \& return num_matches; | |
707 | \& } | |
708 | .Ve | |
709 | .PP | |
710 | .Vb 7 | |
711 | \& main (int argc, char **argv, char **env) | |
712 | \& { | |
713 | \& char *embedding[] = { "", "-e", "0" }; | |
714 | \& AV *match_list; | |
715 | \& I32 num_matches, i; | |
716 | \& SV *text; | |
717 | \& STRLEN n_a; | |
718 | .Ve | |
719 | .PP | |
720 | .Vb 5 | |
721 | \& PERL_SYS_INIT3(&argc,&argv,&env); | |
722 | \& my_perl = perl_alloc(); | |
723 | \& perl_construct(my_perl); | |
724 | \& perl_parse(my_perl, NULL, 3, embedding, NULL); | |
725 | \& PL_exit_flags |= PERL_EXIT_DESTRUCT_END; | |
726 | .Ve | |
727 | .PP | |
728 | .Vb 11 | |
729 | \& text = NEWSV(1099,0); | |
730 | \& sv_setpv(text, "When he is at a convenience store and the " | |
731 | \& "bill comes to some amount like 76 cents, Maynard is " | |
732 | \& "aware that there is something he *should* do, something " | |
733 | \& "that will enable him to get back a quarter, but he has " | |
734 | \& "no idea *what*. He fumbles through his red squeezey " | |
735 | \& "changepurse and gives the boy three extra pennies with " | |
736 | \& "his dollar, hoping that he might luck into the correct " | |
737 | \& "amount. The boy gives him back two of his own pennies " | |
738 | \& "and then the big shiny quarter that is his prize. " | |
739 | \& "-RICHH"); | |
740 | .Ve | |
741 | .PP | |
742 | .Vb 4 | |
743 | \& if (match(text, "m/quarter/")) /** Does text contain 'quarter'? **/ | |
744 | \& printf("match: Text contains the word 'quarter'.\en\en"); | |
745 | \& else | |
746 | \& printf("match: Text doesn't contain the word 'quarter'.\en\en"); | |
747 | .Ve | |
748 | .PP | |
749 | .Vb 4 | |
750 | \& if (match(text, "m/eighth/")) /** Does text contain 'eighth'? **/ | |
751 | \& printf("match: Text contains the word 'eighth'.\en\en"); | |
752 | \& else | |
753 | \& printf("match: Text doesn't contain the word 'eighth'.\en\en"); | |
754 | .Ve | |
755 | .PP | |
756 | .Vb 3 | |
757 | \& /** Match all occurrences of /wi../ **/ | |
758 | \& num_matches = matches(text, "m/(wi..)/g", &match_list); | |
759 | \& printf("matches: m/(wi..)/g found %d matches...\en", num_matches); | |
760 | .Ve | |
761 | .PP | |
762 | .Vb 3 | |
763 | \& for (i = 0; i < num_matches; i++) | |
764 | \& printf("match: %s\en", SvPV(*av_fetch(match_list, i, FALSE),n_a)); | |
765 | \& printf("\en"); | |
766 | .Ve | |
767 | .PP | |
768 | .Vb 7 | |
769 | \& /** Remove all vowels from text **/ | |
770 | \& num_matches = substitute(&text, "s/[aeiou]//gi"); | |
771 | \& if (num_matches) { | |
772 | \& printf("substitute: s/[aeiou]//gi...%d substitutions made.\en", | |
773 | \& num_matches); | |
774 | \& printf("Now text is: %s\en\en", SvPV(text,n_a)); | |
775 | \& } | |
776 | .Ve | |
777 | .PP | |
778 | .Vb 4 | |
779 | \& /** Attempt a substitution **/ | |
780 | \& if (!substitute(&text, "s/Perl/C/")) { | |
781 | \& printf("substitute: s/Perl/C...No substitution made.\en\en"); | |
782 | \& } | |
783 | .Ve | |
784 | .PP | |
785 | .Vb 6 | |
786 | \& SvREFCNT_dec(text); | |
787 | \& PL_perl_destruct_level = 1; | |
788 | \& perl_destruct(my_perl); | |
789 | \& perl_free(my_perl); | |
790 | \& PERL_SYS_TERM(); | |
791 | \& } | |
792 | .Ve | |
793 | .PP | |
794 | which produces the output (again, long lines have been wrapped here) | |
795 | .PP | |
796 | .Vb 1 | |
797 | \& match: Text contains the word 'quarter'. | |
798 | .Ve | |
799 | .PP | |
800 | .Vb 1 | |
801 | \& match: Text doesn't contain the word 'eighth'. | |
802 | .Ve | |
803 | .PP | |
804 | .Vb 3 | |
805 | \& matches: m/(wi..)/g found 2 matches... | |
806 | \& match: will | |
807 | \& match: with | |
808 | .Ve | |
809 | .PP | |
810 | .Vb 6 | |
811 | \& substitute: s/[aeiou]//gi...139 substitutions made. | |
812 | \& Now text is: Whn h s t cnvnnc str nd th bll cms t sm mnt lk 76 cnts, | |
813 | \& Mynrd s wr tht thr s smthng h *shld* d, smthng tht wll nbl hm t gt bck | |
814 | \& qrtr, bt h hs n d *wht*. H fmbls thrgh hs rd sqzy chngprs nd gvs th by | |
815 | \& thr xtr pnns wth hs dllr, hpng tht h mght lck nt th crrct mnt. Th by gvs | |
816 | \& hm bck tw f hs wn pnns nd thn th bg shny qrtr tht s hs prz. -RCHH | |
817 | .Ve | |
818 | .PP | |
819 | .Vb 1 | |
820 | \& substitute: s/Perl/C...No substitution made. | |
821 | .Ve | |
822 | .Sh "Fiddling with the Perl stack from your C program" | |
823 | .IX Subsection "Fiddling with the Perl stack from your C program" | |
824 | When trying to explain stacks, most computer science textbooks mumble | |
825 | something about spring-loaded columns of cafeteria plates: the last | |
826 | thing you pushed on the stack is the first thing you pop off. That'll | |
827 | do for our purposes: your C program will push some arguments onto \*(L"the Perl | |
828 | stack\*(R", shut its eyes while some magic happens, and then pop the | |
829 | results\*(--the return value of your Perl subroutine\*(--off the stack. | |
830 | .PP | |
831 | First you'll need to know how to convert between C types and Perl | |
832 | types, with \fInewSViv()\fR and \fIsv_setnv()\fR and \fInewAV()\fR and all their | |
833 | friends. They're described in perlguts and perlapi. | |
834 | .PP | |
835 | Then you'll need to know how to manipulate the Perl stack. That's | |
836 | described in perlcall. | |
837 | .PP | |
838 | Once you've understood those, embedding Perl in C is easy. | |
839 | .PP | |
840 | Because C has no builtin function for integer exponentiation, let's | |
841 | make Perl's ** operator available to it (this is less useful than it | |
842 | sounds, because Perl implements ** with C's \fI\fIpow()\fI\fR function). First | |
843 | I'll create a stub exponentiation function in \fIpower.pl\fR: | |
844 | .PP | |
845 | .Vb 4 | |
846 | \& sub expo { | |
847 | \& my ($a, $b) = @_; | |
848 | \& return $a ** $b; | |
849 | \& } | |
850 | .Ve | |
851 | .PP | |
852 | Now I'll create a C program, \fIpower.c\fR, with a function | |
853 | \&\fI\fIPerlPower()\fI\fR that contains all the perlguts necessary to push the | |
854 | two arguments into \fI\fIexpo()\fI\fR and to pop the return value out. Take a | |
855 | deep breath... | |
856 | .PP | |
857 | .Vb 2 | |
858 | \& #include <EXTERN.h> | |
859 | \& #include <perl.h> | |
860 | .Ve | |
861 | .PP | |
862 | .Vb 1 | |
863 | \& static PerlInterpreter *my_perl; | |
864 | .Ve | |
865 | .PP | |
866 | .Vb 18 | |
867 | \& static void | |
868 | \& PerlPower(int a, int b) | |
869 | \& { | |
870 | \& dSP; /* initialize stack pointer */ | |
871 | \& ENTER; /* everything created after here */ | |
872 | \& SAVETMPS; /* ...is a temporary variable. */ | |
873 | \& PUSHMARK(SP); /* remember the stack pointer */ | |
874 | \& XPUSHs(sv_2mortal(newSViv(a))); /* push the base onto the stack */ | |
875 | \& XPUSHs(sv_2mortal(newSViv(b))); /* push the exponent onto stack */ | |
876 | \& PUTBACK; /* make local stack pointer global */ | |
877 | \& call_pv("expo", G_SCALAR); /* call the function */ | |
878 | \& SPAGAIN; /* refresh stack pointer */ | |
879 | \& /* pop the return value from stack */ | |
880 | \& printf ("%d to the %dth power is %d.\en", a, b, POPi); | |
881 | \& PUTBACK; | |
882 | \& FREETMPS; /* free that return value */ | |
883 | \& LEAVE; /* ...and the XPUSHed "mortal" args.*/ | |
884 | \& } | |
885 | .Ve | |
886 | .PP | |
887 | .Vb 3 | |
888 | \& int main (int argc, char **argv, char **env) | |
889 | \& { | |
890 | \& char *my_argv[] = { "", "power.pl" }; | |
891 | .Ve | |
892 | .PP | |
893 | .Vb 3 | |
894 | \& PERL_SYS_INIT3(&argc,&argv,&env); | |
895 | \& my_perl = perl_alloc(); | |
896 | \& perl_construct( my_perl ); | |
897 | .Ve | |
898 | .PP | |
899 | .Vb 3 | |
900 | \& perl_parse(my_perl, NULL, 2, my_argv, (char **)NULL); | |
901 | \& PL_exit_flags |= PERL_EXIT_DESTRUCT_END; | |
902 | \& perl_run(my_perl); | |
903 | .Ve | |
904 | .PP | |
905 | .Vb 1 | |
906 | \& PerlPower(3, 4); /*** Compute 3 ** 4 ***/ | |
907 | .Ve | |
908 | .PP | |
909 | .Vb 4 | |
910 | \& perl_destruct(my_perl); | |
911 | \& perl_free(my_perl); | |
912 | \& PERL_SYS_TERM(); | |
913 | \& } | |
914 | .Ve | |
915 | .PP | |
916 | Compile and run: | |
917 | .PP | |
918 | .Vb 1 | |
919 | \& % cc -o power power.c `perl -MExtUtils::Embed -e ccopts -e ldopts` | |
920 | .Ve | |
921 | .PP | |
922 | .Vb 2 | |
923 | \& % power | |
924 | \& 3 to the 4th power is 81. | |
925 | .Ve | |
926 | .Sh "Maintaining a persistent interpreter" | |
927 | .IX Subsection "Maintaining a persistent interpreter" | |
928 | When developing interactive and/or potentially long-running | |
929 | applications, it's a good idea to maintain a persistent interpreter | |
930 | rather than allocating and constructing a new interpreter multiple | |
931 | times. The major reason is speed: since Perl will only be loaded into | |
932 | memory once. | |
933 | .PP | |
934 | However, you have to be more cautious with namespace and variable | |
935 | scoping when using a persistent interpreter. In previous examples | |
936 | we've been using global variables in the default package \f(CW\*(C`main\*(C'\fR. We | |
937 | knew exactly what code would be run, and assumed we could avoid | |
938 | variable collisions and outrageous symbol table growth. | |
939 | .PP | |
940 | Let's say your application is a server that will occasionally run Perl | |
941 | code from some arbitrary file. Your server has no way of knowing what | |
942 | code it's going to run. Very dangerous. | |
943 | .PP | |
944 | If the file is pulled in by \f(CW\*(C`perl_parse()\*(C'\fR, compiled into a newly | |
945 | constructed interpreter, and subsequently cleaned out with | |
946 | \&\f(CW\*(C`perl_destruct()\*(C'\fR afterwards, you're shielded from most namespace | |
947 | troubles. | |
948 | .PP | |
949 | One way to avoid namespace collisions in this scenario is to translate | |
950 | the filename into a guaranteed-unique package name, and then compile | |
951 | the code into that package using \*(L"eval\*(R" in perlfunc. In the example | |
952 | below, each file will only be compiled once. Or, the application | |
953 | might choose to clean out the symbol table associated with the file | |
954 | after it's no longer needed. Using \*(L"call_argv\*(R" in perlapi, We'll | |
955 | call the subroutine \f(CW\*(C`Embed::Persistent::eval_file\*(C'\fR which lives in the | |
956 | file \f(CW\*(C`persistent.pl\*(C'\fR and pass the filename and boolean cleanup/cache | |
957 | flag as arguments. | |
958 | .PP | |
959 | Note that the process will continue to grow for each file that it | |
960 | uses. In addition, there might be \f(CW\*(C`AUTOLOAD\*(C'\fRed subroutines and other | |
961 | conditions that cause Perl's symbol table to grow. You might want to | |
962 | add some logic that keeps track of the process size, or restarts | |
963 | itself after a certain number of requests, to ensure that memory | |
964 | consumption is minimized. You'll also want to scope your variables | |
965 | with \*(L"my\*(R" in perlfunc whenever possible. | |
966 | .PP | |
967 | .Vb 2 | |
968 | \& package Embed::Persistent; | |
969 | \& #persistent.pl | |
970 | .Ve | |
971 | .PP | |
972 | .Vb 3 | |
973 | \& use strict; | |
974 | \& our %Cache; | |
975 | \& use Symbol qw(delete_package); | |
976 | .Ve | |
977 | .PP | |
978 | .Vb 5 | |
979 | \& sub valid_package_name { | |
980 | \& my($string) = @_; | |
981 | \& $string =~ s/([^A-Za-z0-9\e/])/sprintf("_%2x",unpack("C",$1))/eg; | |
982 | \& # second pass only for words starting with a digit | |
983 | \& $string =~ s|/(\ed)|sprintf("/_%2x",unpack("C",$1))|eg; | |
984 | .Ve | |
985 | .PP | |
986 | .Vb 4 | |
987 | \& # Dress it up as a real package name | |
988 | \& $string =~ s|/|::|g; | |
989 | \& return "Embed" . $string; | |
990 | \& } | |
991 | .Ve | |
992 | .PP | |
993 | .Vb 18 | |
994 | \& sub eval_file { | |
995 | \& my($filename, $delete) = @_; | |
996 | \& my $package = valid_package_name($filename); | |
997 | \& my $mtime = -M $filename; | |
998 | \& if(defined $Cache{$package}{mtime} | |
999 | \& && | |
1000 | \& $Cache{$package}{mtime} <= $mtime) | |
1001 | \& { | |
1002 | \& # we have compiled this subroutine already, | |
1003 | \& # it has not been updated on disk, nothing left to do | |
1004 | \& print STDERR "already compiled $package->handler\en"; | |
1005 | \& } | |
1006 | \& else { | |
1007 | \& local *FH; | |
1008 | \& open FH, $filename or die "open '$filename' $!"; | |
1009 | \& local($/) = undef; | |
1010 | \& my $sub = <FH>; | |
1011 | \& close FH; | |
1012 | .Ve | |
1013 | .PP | |
1014 | .Vb 8 | |
1015 | \& #wrap the code into a subroutine inside our unique package | |
1016 | \& my $eval = qq{package $package; sub handler { $sub; }}; | |
1017 | \& { | |
1018 | \& # hide our variables within this block | |
1019 | \& my($filename,$mtime,$package,$sub); | |
1020 | \& eval $eval; | |
1021 | \& } | |
1022 | \& die $@ if $@; | |
1023 | .Ve | |
1024 | .PP | |
1025 | .Vb 3 | |
1026 | \& #cache it unless we're cleaning out each time | |
1027 | \& $Cache{$package}{mtime} = $mtime unless $delete; | |
1028 | \& } | |
1029 | .Ve | |
1030 | .PP | |
1031 | .Vb 2 | |
1032 | \& eval {$package->handler;}; | |
1033 | \& die $@ if $@; | |
1034 | .Ve | |
1035 | .PP | |
1036 | .Vb 1 | |
1037 | \& delete_package($package) if $delete; | |
1038 | .Ve | |
1039 | .PP | |
1040 | .Vb 3 | |
1041 | \& #take a look if you want | |
1042 | \& #print Devel::Symdump->rnew($package)->as_string, $/; | |
1043 | \& } | |
1044 | .Ve | |
1045 | .PP | |
1046 | .Vb 1 | |
1047 | \& 1; | |
1048 | .Ve | |
1049 | .PP | |
1050 | .Vb 1 | |
1051 | \& __END__ | |
1052 | .Ve | |
1053 | .PP | |
1054 | .Vb 3 | |
1055 | \& /* persistent.c */ | |
1056 | \& #include <EXTERN.h> | |
1057 | \& #include <perl.h> | |
1058 | .Ve | |
1059 | .PP | |
1060 | .Vb 4 | |
1061 | \& /* 1 = clean out filename's symbol table after each request, 0 = don't */ | |
1062 | \& #ifndef DO_CLEAN | |
1063 | \& #define DO_CLEAN 0 | |
1064 | \& #endif | |
1065 | .Ve | |
1066 | .PP | |
1067 | .Vb 1 | |
1068 | \& #define BUFFER_SIZE 1024 | |
1069 | .Ve | |
1070 | .PP | |
1071 | .Vb 1 | |
1072 | \& static PerlInterpreter *my_perl = NULL; | |
1073 | .Ve | |
1074 | .PP | |
1075 | .Vb 8 | |
1076 | \& int | |
1077 | \& main(int argc, char **argv, char **env) | |
1078 | \& { | |
1079 | \& char *embedding[] = { "", "persistent.pl" }; | |
1080 | \& char *args[] = { "", DO_CLEAN, NULL }; | |
1081 | \& char filename[BUFFER_SIZE]; | |
1082 | \& int exitstatus = 0; | |
1083 | \& STRLEN n_a; | |
1084 | .Ve | |
1085 | .PP | |
1086 | .Vb 6 | |
1087 | \& PERL_SYS_INIT3(&argc,&argv,&env); | |
1088 | \& if((my_perl = perl_alloc()) == NULL) { | |
1089 | \& fprintf(stderr, "no memory!"); | |
1090 | \& exit(1); | |
1091 | \& } | |
1092 | \& perl_construct(my_perl); | |
1093 | .Ve | |
1094 | .PP | |
1095 | .Vb 4 | |
1096 | \& exitstatus = perl_parse(my_perl, NULL, 2, embedding, NULL); | |
1097 | \& PL_exit_flags |= PERL_EXIT_DESTRUCT_END; | |
1098 | \& if(!exitstatus) { | |
1099 | \& exitstatus = perl_run(my_perl); | |
1100 | .Ve | |
1101 | .PP | |
1102 | .Vb 2 | |
1103 | \& while(printf("Enter file name: ") && | |
1104 | \& fgets(filename, BUFFER_SIZE, stdin)) { | |
1105 | .Ve | |
1106 | .PP | |
1107 | .Vb 5 | |
1108 | \& filename[strlen(filename)-1] = '\e0'; /* strip \en */ | |
1109 | \& /* call the subroutine, passing it the filename as an argument */ | |
1110 | \& args[0] = filename; | |
1111 | \& call_argv("Embed::Persistent::eval_file", | |
1112 | \& G_DISCARD | G_EVAL, args); | |
1113 | .Ve | |
1114 | .PP | |
1115 | .Vb 5 | |
1116 | \& /* check $@ */ | |
1117 | \& if(SvTRUE(ERRSV)) | |
1118 | \& fprintf(stderr, "eval error: %s\en", SvPV(ERRSV,n_a)); | |
1119 | \& } | |
1120 | \& } | |
1121 | .Ve | |
1122 | .PP | |
1123 | .Vb 6 | |
1124 | \& PL_perl_destruct_level = 0; | |
1125 | \& perl_destruct(my_perl); | |
1126 | \& perl_free(my_perl); | |
1127 | \& PERL_SYS_TERM(); | |
1128 | \& exit(exitstatus); | |
1129 | \& } | |
1130 | .Ve | |
1131 | .PP | |
1132 | Now compile: | |
1133 | .PP | |
1134 | .Vb 1 | |
1135 | \& % cc -o persistent persistent.c `perl -MExtUtils::Embed -e ccopts -e ldopts` | |
1136 | .Ve | |
1137 | .PP | |
1138 | Here's an example script file: | |
1139 | .PP | |
1140 | .Vb 3 | |
1141 | \& #test.pl | |
1142 | \& my $string = "hello"; | |
1143 | \& foo($string); | |
1144 | .Ve | |
1145 | .PP | |
1146 | .Vb 3 | |
1147 | \& sub foo { | |
1148 | \& print "foo says: @_\en"; | |
1149 | \& } | |
1150 | .Ve | |
1151 | .PP | |
1152 | Now run: | |
1153 | .PP | |
1154 | .Vb 7 | |
1155 | \& % persistent | |
1156 | \& Enter file name: test.pl | |
1157 | \& foo says: hello | |
1158 | \& Enter file name: test.pl | |
1159 | \& already compiled Embed::test_2epl->handler | |
1160 | \& foo says: hello | |
1161 | \& Enter file name: ^C | |
1162 | .Ve | |
1163 | .Sh "Execution of \s-1END\s0 blocks" | |
1164 | .IX Subsection "Execution of END blocks" | |
1165 | Traditionally \s-1END\s0 blocks have been executed at the end of the perl_run. | |
1166 | This causes problems for applications that never call perl_run. Since | |
1167 | perl 5.7.2 you can specify \f(CW\*(C`PL_exit_flags |= PERL_EXIT_DESTRUCT_END\*(C'\fR | |
1168 | to get the new behaviour. This also enables the running of \s-1END\s0 blocks if | |
1169 | the perl_parse fails and \f(CW\*(C`perl_destruct\*(C'\fR will return the exit value. | |
1170 | .Sh "Maintaining multiple interpreter instances" | |
1171 | .IX Subsection "Maintaining multiple interpreter instances" | |
1172 | Some rare applications will need to create more than one interpreter | |
1173 | during a session. Such an application might sporadically decide to | |
1174 | release any resources associated with the interpreter. | |
1175 | .PP | |
1176 | The program must take care to ensure that this takes place \fIbefore\fR | |
1177 | the next interpreter is constructed. By default, when perl is not | |
1178 | built with any special options, the global variable | |
1179 | \&\f(CW\*(C`PL_perl_destruct_level\*(C'\fR is set to \f(CW0\fR, since extra cleaning isn't | |
1180 | usually needed when a program only ever creates a single interpreter | |
1181 | in its entire lifetime. | |
1182 | .PP | |
1183 | Setting \f(CW\*(C`PL_perl_destruct_level\*(C'\fR to \f(CW1\fR makes everything squeaky clean: | |
1184 | .PP | |
1185 | .Vb 13 | |
1186 | \& while(1) { | |
1187 | \& ... | |
1188 | \& /* reset global variables here with PL_perl_destruct_level = 1 */ | |
1189 | \& PL_perl_destruct_level = 1; | |
1190 | \& perl_construct(my_perl); | |
1191 | \& ... | |
1192 | \& /* clean and reset _everything_ during perl_destruct */ | |
1193 | \& PL_perl_destruct_level = 1; | |
1194 | \& perl_destruct(my_perl); | |
1195 | \& perl_free(my_perl); | |
1196 | \& ... | |
1197 | \& /* let's go do it again! */ | |
1198 | \& } | |
1199 | .Ve | |
1200 | .PP | |
1201 | When \fI\fIperl_destruct()\fI\fR is called, the interpreter's syntax parse tree | |
1202 | and symbol tables are cleaned up, and global variables are reset. The | |
1203 | second assignment to \f(CW\*(C`PL_perl_destruct_level\*(C'\fR is needed because | |
1204 | perl_construct resets it to \f(CW0\fR. | |
1205 | .PP | |
1206 | Now suppose we have more than one interpreter instance running at the | |
1207 | same time. This is feasible, but only if you used the Configure option | |
1208 | \&\f(CW\*(C`\-Dusemultiplicity\*(C'\fR or the options \f(CW\*(C`\-Dusethreads \-Duseithreads\*(C'\fR when | |
1209 | building perl. By default, enabling one of these Configure options | |
1210 | sets the per-interpreter global variable \f(CW\*(C`PL_perl_destruct_level\*(C'\fR to | |
1211 | \&\f(CW1\fR, so that thorough cleaning is automatic and interpreter variables | |
1212 | are initialized correctly. Even if you don't intend to run two or | |
1213 | more interpreters at the same time, but to run them sequentially, like | |
1214 | in the above example, it is recommended to build perl with the | |
1215 | \&\f(CW\*(C`\-Dusemultiplicity\*(C'\fR option otherwise some interpreter variables may | |
1216 | not be initialized correctly between consecutive runs and your | |
1217 | application may crash. | |
1218 | .PP | |
1219 | Using \f(CW\*(C`\-Dusethreads \-Duseithreads\*(C'\fR rather than \f(CW\*(C`\-Dusemultiplicity\*(C'\fR | |
1220 | is more appropriate if you intend to run multiple interpreters | |
1221 | concurrently in different threads, because it enables support for | |
1222 | linking in the thread libraries of your system with the interpreter. | |
1223 | .PP | |
1224 | Let's give it a try: | |
1225 | .PP | |
1226 | .Vb 2 | |
1227 | \& #include <EXTERN.h> | |
1228 | \& #include <perl.h> | |
1229 | .Ve | |
1230 | .PP | |
1231 | .Vb 2 | |
1232 | \& /* we're going to embed two interpreters */ | |
1233 | \& /* we're going to embed two interpreters */ | |
1234 | .Ve | |
1235 | .PP | |
1236 | .Vb 1 | |
1237 | \& #define SAY_HELLO "-e", "print qq(Hi, I'm $^X\en)" | |
1238 | .Ve | |
1239 | .PP | |
1240 | .Vb 5 | |
1241 | \& int main(int argc, char **argv, char **env) | |
1242 | \& { | |
1243 | \& PerlInterpreter *one_perl, *two_perl; | |
1244 | \& char *one_args[] = { "one_perl", SAY_HELLO }; | |
1245 | \& char *two_args[] = { "two_perl", SAY_HELLO }; | |
1246 | .Ve | |
1247 | .PP | |
1248 | .Vb 3 | |
1249 | \& PERL_SYS_INIT3(&argc,&argv,&env); | |
1250 | \& one_perl = perl_alloc(); | |
1251 | \& two_perl = perl_alloc(); | |
1252 | .Ve | |
1253 | .PP | |
1254 | .Vb 4 | |
1255 | \& PERL_SET_CONTEXT(one_perl); | |
1256 | \& perl_construct(one_perl); | |
1257 | \& PERL_SET_CONTEXT(two_perl); | |
1258 | \& perl_construct(two_perl); | |
1259 | .Ve | |
1260 | .PP | |
1261 | .Vb 4 | |
1262 | \& PERL_SET_CONTEXT(one_perl); | |
1263 | \& perl_parse(one_perl, NULL, 3, one_args, (char **)NULL); | |
1264 | \& PERL_SET_CONTEXT(two_perl); | |
1265 | \& perl_parse(two_perl, NULL, 3, two_args, (char **)NULL); | |
1266 | .Ve | |
1267 | .PP | |
1268 | .Vb 4 | |
1269 | \& PERL_SET_CONTEXT(one_perl); | |
1270 | \& perl_run(one_perl); | |
1271 | \& PERL_SET_CONTEXT(two_perl); | |
1272 | \& perl_run(two_perl); | |
1273 | .Ve | |
1274 | .PP | |
1275 | .Vb 4 | |
1276 | \& PERL_SET_CONTEXT(one_perl); | |
1277 | \& perl_destruct(one_perl); | |
1278 | \& PERL_SET_CONTEXT(two_perl); | |
1279 | \& perl_destruct(two_perl); | |
1280 | .Ve | |
1281 | .PP | |
1282 | .Vb 6 | |
1283 | \& PERL_SET_CONTEXT(one_perl); | |
1284 | \& perl_free(one_perl); | |
1285 | \& PERL_SET_CONTEXT(two_perl); | |
1286 | \& perl_free(two_perl); | |
1287 | \& PERL_SYS_TERM(); | |
1288 | \& } | |
1289 | .Ve | |
1290 | .PP | |
1291 | Note the calls to \s-1\fIPERL_SET_CONTEXT\s0()\fR. These are necessary to initialize | |
1292 | the global state that tracks which interpreter is the \*(L"current\*(R" one on | |
1293 | the particular process or thread that may be running it. It should | |
1294 | always be used if you have more than one interpreter and are making | |
1295 | perl \s-1API\s0 calls on both interpreters in an interleaved fashion. | |
1296 | .PP | |
1297 | \&\s-1PERL_SET_CONTEXT\s0(interp) should also be called whenever \f(CW\*(C`interp\*(C'\fR is | |
1298 | used by a thread that did not create it (using either \fIperl_alloc()\fR, or | |
1299 | the more esoteric \fIperl_clone()\fR). | |
1300 | .PP | |
1301 | Compile as usual: | |
1302 | .PP | |
1303 | .Vb 1 | |
1304 | \& % cc -o multiplicity multiplicity.c `perl -MExtUtils::Embed -e ccopts -e ldopts` | |
1305 | .Ve | |
1306 | .PP | |
1307 | Run it, Run it: | |
1308 | .PP | |
1309 | .Vb 3 | |
1310 | \& % multiplicity | |
1311 | \& Hi, I'm one_perl | |
1312 | \& Hi, I'm two_perl | |
1313 | .Ve | |
1314 | .Sh "Using Perl modules, which themselves use C libraries, from your C program" | |
1315 | .IX Subsection "Using Perl modules, which themselves use C libraries, from your C program" | |
1316 | If you've played with the examples above and tried to embed a script | |
1317 | that \fI\fIuse()\fI\fRs a Perl module (such as \fISocket\fR) which itself uses a C or \*(C+ library, | |
1318 | this probably happened: | |
1319 | .PP | |
1320 | .Vb 3 | |
1321 | \& Can't load module Socket, dynamic loading not available in this perl. | |
1322 | \& (You may need to build a new perl executable which either supports | |
1323 | \& dynamic loading or has the Socket module statically linked into it.) | |
1324 | .Ve | |
1325 | .PP | |
1326 | What's wrong? | |
1327 | .PP | |
1328 | Your interpreter doesn't know how to communicate with these extensions | |
1329 | on its own. A little glue will help. Up until now you've been | |
1330 | calling \fI\fIperl_parse()\fI\fR, handing it \s-1NULL\s0 for the second argument: | |
1331 | .PP | |
1332 | .Vb 1 | |
1333 | \& perl_parse(my_perl, NULL, argc, my_argv, NULL); | |
1334 | .Ve | |
1335 | .PP | |
1336 | That's where the glue code can be inserted to create the initial contact between | |
1337 | Perl and linked C/\*(C+ routines. Let's take a look some pieces of \fIperlmain.c\fR | |
1338 | to see how Perl does this: | |
1339 | .PP | |
1340 | .Vb 1 | |
1341 | \& static void xs_init (pTHX); | |
1342 | .Ve | |
1343 | .PP | |
1344 | .Vb 2 | |
1345 | \& EXTERN_C void boot_DynaLoader (pTHX_ CV* cv); | |
1346 | \& EXTERN_C void boot_Socket (pTHX_ CV* cv); | |
1347 | .Ve | |
1348 | .PP | |
1349 | .Vb 8 | |
1350 | \& EXTERN_C void | |
1351 | \& xs_init(pTHX) | |
1352 | \& { | |
1353 | \& char *file = __FILE__; | |
1354 | \& /* DynaLoader is a special case */ | |
1355 | \& newXS("DynaLoader::boot_DynaLoader", boot_DynaLoader, file); | |
1356 | \& newXS("Socket::bootstrap", boot_Socket, file); | |
1357 | \& } | |
1358 | .Ve | |
1359 | .PP | |
1360 | Simply put: for each extension linked with your Perl executable | |
1361 | (determined during its initial configuration on your | |
1362 | computer or when adding a new extension), | |
1363 | a Perl subroutine is created to incorporate the extension's | |
1364 | routines. Normally, that subroutine is named | |
1365 | \&\fI\fIModule::bootstrap()\fI\fR and is invoked when you say \fIuse Module\fR. In | |
1366 | turn, this hooks into an \s-1XSUB\s0, \fIboot_Module\fR, which creates a Perl | |
1367 | counterpart for each of the extension's XSUBs. Don't worry about this | |
1368 | part; leave that to the \fIxsubpp\fR and extension authors. If your | |
1369 | extension is dynamically loaded, DynaLoader creates \fI\fIModule::bootstrap()\fI\fR | |
1370 | for you on the fly. In fact, if you have a working DynaLoader then there | |
1371 | is rarely any need to link in any other extensions statically. | |
1372 | .PP | |
1373 | Once you have this code, slap it into the second argument of \fI\fIperl_parse()\fI\fR: | |
1374 | .PP | |
1375 | .Vb 1 | |
1376 | \& perl_parse(my_perl, xs_init, argc, my_argv, NULL); | |
1377 | .Ve | |
1378 | .PP | |
1379 | Then compile: | |
1380 | .PP | |
1381 | .Vb 1 | |
1382 | \& % cc -o interp interp.c `perl -MExtUtils::Embed -e ccopts -e ldopts` | |
1383 | .Ve | |
1384 | .PP | |
1385 | .Vb 3 | |
1386 | \& % interp | |
1387 | \& use Socket; | |
1388 | \& use SomeDynamicallyLoadedModule; | |
1389 | .Ve | |
1390 | .PP | |
1391 | .Vb 1 | |
1392 | \& print "Now I can use extensions!\en"' | |
1393 | .Ve | |
1394 | .PP | |
1395 | \&\fBExtUtils::Embed\fR can also automate writing the \fIxs_init\fR glue code. | |
1396 | .PP | |
1397 | .Vb 4 | |
1398 | \& % perl -MExtUtils::Embed -e xsinit -- -o perlxsi.c | |
1399 | \& % cc -c perlxsi.c `perl -MExtUtils::Embed -e ccopts` | |
1400 | \& % cc -c interp.c `perl -MExtUtils::Embed -e ccopts` | |
1401 | \& % cc -o interp perlxsi.o interp.o `perl -MExtUtils::Embed -e ldopts` | |
1402 | .Ve | |
1403 | .PP | |
1404 | Consult perlxs, perlguts, and perlapi for more details. | |
1405 | .SH "Embedding Perl under Win32" | |
1406 | .IX Header "Embedding Perl under Win32" | |
1407 | In general, all of the source code shown here should work unmodified under | |
1408 | Windows. | |
1409 | .PP | |
1410 | However, there are some caveats about the command-line examples shown. | |
1411 | For starters, backticks won't work under the Win32 native command shell. | |
1412 | The ExtUtils::Embed kit on \s-1CPAN\s0 ships with a script called | |
1413 | \&\fBgenmake\fR, which generates a simple makefile to build a program from | |
1414 | a single C source file. It can be used like this: | |
1415 | .PP | |
1416 | .Vb 3 | |
1417 | \& C:\eExtUtils-Embed\eeg> perl genmake interp.c | |
1418 | \& C:\eExtUtils-Embed\eeg> nmake | |
1419 | \& C:\eExtUtils-Embed\eeg> interp -e "print qq{I'm embedded in Win32!\en}" | |
1420 | .Ve | |
1421 | .PP | |
1422 | You may wish to use a more robust environment such as the Microsoft | |
1423 | Developer Studio. In this case, run this to generate perlxsi.c: | |
1424 | .PP | |
1425 | .Vb 1 | |
1426 | \& perl -MExtUtils::Embed -e xsinit | |
1427 | .Ve | |
1428 | .PP | |
1429 | Create a new project and Insert \-> Files into Project: perlxsi.c, | |
1430 | perl.lib, and your own source files, e.g. interp.c. Typically you'll | |
1431 | find perl.lib in \fBC:\eperl\elib\eCORE\fR, if not, you should see the | |
1432 | \&\fB\s-1CORE\s0\fR directory relative to \f(CW\*(C`perl \-V:archlib\*(C'\fR. The studio will | |
1433 | also need this path so it knows where to find Perl include files. | |
1434 | This path can be added via the Tools \-> Options \-> Directories menu. | |
1435 | Finally, select Build \-> Build interp.exe and you're ready to go. | |
1436 | .SH "Hiding Perl_" | |
1437 | .IX Header "Hiding Perl_" | |
1438 | If you completely hide the short forms forms of the Perl public \s-1API\s0, | |
1439 | add \-DPERL_NO_SHORT_NAMES to the compilation flags. This means that | |
1440 | for example instead of writing | |
1441 | .PP | |
1442 | .Vb 1 | |
1443 | \& warn("%d bottles of beer on the wall", bottlecount); | |
1444 | .Ve | |
1445 | .PP | |
1446 | you will have to write the explicit full form | |
1447 | .PP | |
1448 | .Vb 1 | |
1449 | \& Perl_warn(aTHX_ "%d bottles of beer on the wall", bottlecount); | |
1450 | .Ve | |
1451 | .PP | |
1452 | (See "Background and \s-1PERL_IMPLICIT_CONTEXT\s0 for the explanation of the \f(CW\*(C`aTHX_\*(C'\fR." in perlguts ) Hiding the short forms is very useful for avoiding | |
1453 | all sorts of nasty (C preprocessor or otherwise) conflicts with other | |
1454 | software packages (Perl defines about 2400 APIs with these short names, | |
1455 | take or leave few hundred, so there certainly is room for conflict.) | |
1456 | .SH "MORAL" | |
1457 | .IX Header "MORAL" | |
1458 | You can sometimes \fIwrite faster code\fR in C, but | |
1459 | you can always \fIwrite code faster\fR in Perl. Because you can use | |
1460 | each from the other, combine them as you wish. | |
1461 | .SH "AUTHOR" | |
1462 | .IX Header "AUTHOR" | |
1463 | Jon Orwant <\fIorwant@media.mit.edu\fR> and Doug MacEachern | |
1464 | <\fIdougm@covalent.net\fR>, with small contributions from Tim Bunce, Tom | |
1465 | Christiansen, Guy Decoux, Hallvard Furuseth, Dov Grobgeld, and Ilya | |
1466 | Zakharevich. | |
1467 | .PP | |
1468 | Doug MacEachern has an article on embedding in Volume 1, Issue 4 of | |
1469 | The Perl Journal ( http://www.tpj.com/ ). Doug is also the developer of the | |
1470 | most widely-used Perl embedding: the mod_perl system | |
1471 | (perl.apache.org), which embeds Perl in the Apache web server. | |
1472 | Oracle, Binary Evolution, ActiveState, and Ben Sugars's nsapi_perl | |
1473 | have used this model for Oracle, Netscape and Internet Information | |
1474 | Server Perl plugins. | |
1475 | .SH "COPYRIGHT" | |
1476 | .IX Header "COPYRIGHT" | |
1477 | Copyright (C) 1995, 1996, 1997, 1998 Doug MacEachern and Jon Orwant. All | |
1478 | Rights Reserved. | |
1479 | .PP | |
1480 | Permission is granted to make and distribute verbatim copies of this | |
1481 | documentation provided the copyright notice and this permission notice are | |
1482 | preserved on all copies. | |
1483 | .PP | |
1484 | Permission is granted to copy and distribute modified versions of this | |
1485 | documentation under the conditions for verbatim copying, provided also | |
1486 | that they are marked clearly as modified versions, that the authors' | |
1487 | names and title are unchanged (though subtitles and additional | |
1488 | authors' names may be added), and that the entire resulting derived | |
1489 | work is distributed under the terms of a permission notice identical | |
1490 | to this one. | |
1491 | .PP | |
1492 | Permission is granted to copy and distribute translations of this | |
1493 | documentation into another language, under the above conditions for | |
1494 | modified versions. |