Embedding

[perl5.git] / pod / perlembed.pod

diff --git a/pod/perlembed.pod b/pod/perlembed.pod
index 24385dd..3b28244 100644 (file)
--- a/pod/perlembed.pod
+++ b/pod/perlembed.pod
@@ -183,6 +183,7 @@ version of I<miniperlmain.c> containing the essentials of embedding:
 
     int main(int argc, char **argv, char **env)
     {
 
     int main(int argc, char **argv, char **env)
     {

+       PERL_SYS_INIT3(&argc,&argv,&env);

         my_perl = perl_alloc();
         perl_construct(my_perl);
        PL_exit_flags |= PERL_EXIT_DESTRUCT_END;
         my_perl = perl_alloc();
         perl_construct(my_perl);
        PL_exit_flags |= PERL_EXIT_DESTRUCT_END;


@@ -190,11 +191,16 @@ version of I<miniperlmain.c> containing the essentials of embedding:
         perl_run(my_perl);
         perl_destruct(my_perl);
         perl_free(my_perl);
         perl_run(my_perl);
         perl_destruct(my_perl);
         perl_free(my_perl);

+       PERL_SYS_TERM();

     }
 
 Notice that we don't use the C<env> pointer.  Normally handed to
 C<perl_parse> as its final argument, C<env> here is replaced by
     }
 
 Notice that we don't use the C<env> pointer.  Normally handed to
 C<perl_parse> as its final argument, C<env> here is replaced by

-C<NULL>, which means that the current environment will be used.
+C<NULL>, which means that the current environment will be used.  The macros
+PERL_SYS_INIT3() and PERL_SYS_TERM() provide system-specific tune up 
+of the C runtime environment necessary to run Perl interpreters; since
+PERL_SYS_INIT3() may change C<env>, it may be more appropriate to provide
+C<env> as an argument to perl_parse().

 
 Now compile this program (I'll call it I<interp.c>) into an executable:
 
 
 Now compile this program (I'll call it I<interp.c>) into an executable:
 


@@ -235,6 +241,7 @@ That's shown below, in a program I'll call I<showtime.c>.
     int main(int argc, char **argv, char **env)
     {
         char *args[] = { NULL };
     int main(int argc, char **argv, char **env)
     {
         char *args[] = { NULL };

+       PERL_SYS_INIT3(&argc,&argv,&env);

         my_perl = perl_alloc();
         perl_construct(my_perl);
 
         my_perl = perl_alloc();
         perl_construct(my_perl);
 


@@ -247,6 +254,7 @@ That's shown below, in a program I'll call I<showtime.c>.
 
         perl_destruct(my_perl);
         perl_free(my_perl);
 
         perl_destruct(my_perl);
         perl_free(my_perl);

+       PERL_SYS_TERM();

     }
 
 where I<showtime> is a Perl subroutine that takes no arguments (that's the
     }
 
 where I<showtime> is a Perl subroutine that takes no arguments (that's the


@@ -308,6 +316,7 @@ the first, a C<float> from the second, and a C<char *> from the third.
        STRLEN n_a;
        char *embedding[] = { "", "-e", "0" };
 
        STRLEN n_a;
        char *embedding[] = { "", "-e", "0" };
 

+       PERL_SYS_INIT3(&argc,&argv,&env);

        my_perl = perl_alloc();
        perl_construct( my_perl );
 
        my_perl = perl_alloc();
        perl_construct( my_perl );
 


@@ -329,6 +338,7 @@ the first, a C<float> from the second, and a C<char *> from the third.
 
        perl_destruct(my_perl);
        perl_free(my_perl);
 
        perl_destruct(my_perl);
        perl_free(my_perl);

+       PERL_SYS_TERM();

    }
 
 All of those strange functions with I<sv> in their names help convert Perl scalars to C types.  They're described in L<perlguts> and L<perlapi>.
    }
 
 All of those strange functions with I<sv> in their names help convert Perl scalars to C types.  They're described in L<perlguts> and L<perlapi>.


@@ -489,6 +499,7 @@ been wrapped here):
      SV *text;
      STRLEN n_a;
 
      SV *text;
      STRLEN n_a;
 

+     PERL_SYS_INIT3(&argc,&argv,&env);

      my_perl = perl_alloc();
      perl_construct(my_perl);
      perl_parse(my_perl, NULL, 3, embedding, NULL);
      my_perl = perl_alloc();
      perl_construct(my_perl);
      perl_parse(my_perl, NULL, 3, embedding, NULL);


@@ -532,6 +543,7 @@ been wrapped here):
      PL_perl_destruct_level = 1;
      perl_destruct(my_perl);
      perl_free(my_perl);
      PL_perl_destruct_level = 1;
      perl_destruct(my_perl);
      perl_free(my_perl);

+     PERL_SYS_TERM();

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


@@ -614,6 +626,7 @@ deep breath...
     {
       char *my_argv[] = { "", "power.pl" };
 
     {
       char *my_argv[] = { "", "power.pl" };
 

+      PERL_SYS_INIT3(&argc,&argv,&env);

       my_perl = perl_alloc();
       perl_construct( my_perl );
 
       my_perl = perl_alloc();
       perl_construct( my_perl );
 


@@ -625,6 +638,7 @@ deep breath...
 
       perl_destruct(my_perl);
       perl_free(my_perl);
 
       perl_destruct(my_perl);
       perl_free(my_perl);

+      PERL_SYS_TERM();

     }
 
 
     }
 
 


@@ -750,6 +764,8 @@ with L<perlfunc/my> whenever possible.
  #define DO_CLEAN 0
  #endif
 
  #define DO_CLEAN 0
  #endif
 

+ #define BUFFER_SIZE 1024
+

  static PerlInterpreter *my_perl = NULL;
 
  int
  static PerlInterpreter *my_perl = NULL;
 
  int


@@ -757,10 +773,11 @@ with L<perlfunc/my> whenever possible.
  {
      char *embedding[] = { "", "persistent.pl" };
      char *args[] = { "", DO_CLEAN, NULL };
  {
      char *embedding[] = { "", "persistent.pl" };
      char *args[] = { "", DO_CLEAN, NULL };

-     char filename [1024];
+     char filename[BUFFER_SIZE];

      int exitstatus = 0;
      STRLEN n_a;
 
      int exitstatus = 0;
      STRLEN n_a;
 

+     PERL_SYS_INIT3(&argc,&argv,&env);

      if((my_perl = perl_alloc()) == NULL) {
         fprintf(stderr, "no memory!");
         exit(1);
      if((my_perl = perl_alloc()) == NULL) {
         fprintf(stderr, "no memory!");
         exit(1);


@@ -772,8 +789,10 @@ with L<perlfunc/my> whenever possible.
      if(!exitstatus) {
         exitstatus = perl_run(my_perl);
 
      if(!exitstatus) {
         exitstatus = perl_run(my_perl);
 

-        while(printf("Enter file name: ") && gets(filename)) {
+        while(printf("Enter file name: ") &&
+              fgets(filename, BUFFER_SIZE, stdin)) {

 
 

+            filename[strlen(filename)-1] = '\0'; /* strip \n */

             /* call the subroutine, passing it the filename as an argument */
             args[0] = filename;
             call_argv("Embed::Persistent::eval_file",
             /* call the subroutine, passing it the filename as an argument */
             args[0] = filename;
             call_argv("Embed::Persistent::eval_file",


@@ -788,6 +807,7 @@ with L<perlfunc/my> whenever possible.
      PL_perl_destruct_level = 0;
      perl_destruct(my_perl);
      perl_free(my_perl);
      PL_perl_destruct_level = 0;
      perl_destruct(my_perl);
      perl_free(my_perl);

+     PERL_SYS_TERM();

      exit(exitstatus);
  }
 
      exit(exitstatus);
  }
 


@@ -880,12 +900,14 @@ Let's give it a try:
 
  int main(int argc, char **argv, char **env)
  {
 
  int main(int argc, char **argv, char **env)
  {

-     PerlInterpreter
-         *one_perl = perl_alloc(),
-         *two_perl = perl_alloc();
+     PerlInterpreter *one_perl, *two_perl;

      char *one_args[] = { "one_perl", SAY_HELLO };
      char *two_args[] = { "two_perl", SAY_HELLO };
 
      char *one_args[] = { "one_perl", SAY_HELLO };
      char *two_args[] = { "two_perl", SAY_HELLO };
 

+     PERL_SYS_INIT3(&argc,&argv,&env);
+     one_perl = perl_alloc();
+     two_perl = perl_alloc();
+

      PERL_SET_CONTEXT(one_perl);
      perl_construct(one_perl);
      PERL_SET_CONTEXT(two_perl);
      PERL_SET_CONTEXT(one_perl);
      perl_construct(one_perl);
      PERL_SET_CONTEXT(two_perl);


@@ -910,6 +932,7 @@ Let's give it a try:
      perl_free(one_perl);
      PERL_SET_CONTEXT(two_perl);
      perl_free(two_perl);
      perl_free(one_perl);
      PERL_SET_CONTEXT(two_perl);
      perl_free(two_perl);

+     PERL_SYS_TERM();

  }
 
 Note the calls to PERL_SET_CONTEXT().  These are necessary to initialize
  }
 
 Note the calls to PERL_SET_CONTEXT().  These are necessary to initialize


@@ -1041,7 +1064,7 @@ Finally, select Build -> Build interp.exe and you're ready to go.
 =head1 Hiding Perl_
 
 If you completely hide the short forms forms of the Perl public API,
 =head1 Hiding Perl_
 
 If you completely hide the short forms forms of the Perl public API,

-add -DPERL_HIDE_SHORT_NAMES to the compilation flags.  This means that
+add -DPERL_NO_SHORT_NAMES to the compilation flags.  This means that

 for example instead of writing
 
     warn("%d bottles of beer on the wall", bottlecount);
 for example instead of writing
 
     warn("%d bottles of beer on the wall", bottlecount);