document PERL_SYS_INIT, PERL_SYS_TERM and that they should only be used once

1 files changed, 10 insertions, 5 deletions

diff --git a/pod/perlembed.pod b/pod/perlembed.pod
index 39364eb429..161e1ceff5 100644
--- a/pod/perlembed.pod
+++ b/pod/perlembed.pod
@@ -196,11 +196,16 @@ version of I<miniperlmain.c> containing the essentials of embedding:
 
 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.  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().
+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;
+they should only be called once regardless of how many interpreters you
+create or destroy. Call PERL_SYS_INIT3() before you create your first
+interpreter, and PERL_SYS_TERM() after you free your last interpreter.
+
+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: