X-Git-Url: https://perl5.git.perl.org/perl5.git/blobdiff_plain/35209cc889c47c22db67b1eb1f83d963b429057a..1ccffcf53e06b538ce52bce400c2322285291267:/pod/perlembed.pod

diff --git a/pod/perlembed.pod b/pod/perlembed.pod
index 24385dd..3b28244 100644
--- 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)
     {
+	PERL_SYS_INIT3(&argc,&argv,&env);
         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_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
-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:
 
@@ -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 };
+	PERL_SYS_INIT3(&argc,&argv,&env);
         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_SYS_TERM();
     }
 
 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" };
 
+       PERL_SYS_INIT3(&argc,&argv,&env);
        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_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>.
@@ -489,6 +499,7 @@ been wrapped here):
      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);
@@ -532,6 +543,7 @@ been wrapped here):
      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)
@@ -614,6 +626,7 @@ deep breath...
     {
       char *my_argv[] = { "", "power.pl" };
 
+      PERL_SYS_INIT3(&argc,&argv,&env);
       my_perl = perl_alloc();
       perl_construct( my_perl );
 
@@ -625,6 +638,7 @@ deep breath...
 
       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 BUFFER_SIZE 1024
+
  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 filename [1024];
+     char filename[BUFFER_SIZE];
      int exitstatus = 0;
      STRLEN n_a;
 
+     PERL_SYS_INIT3(&argc,&argv,&env);
      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);
 
-        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",
@@ -788,6 +807,7 @@ with L<perlfunc/my> whenever possible.
      PL_perl_destruct_level = 0;
      perl_destruct(my_perl);
      perl_free(my_perl);
+     PERL_SYS_TERM();
      exit(exitstatus);
  }
 
@@ -880,12 +900,14 @@ Let's give it a try:
 
  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 };
 
+     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);
@@ -910,6 +932,7 @@ Let's give it a try:
      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
@@ -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,
-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);