Integrate:

[ 23546]
Doc nit for B::Lint
Subject: [PATCH] B::Lint
Message-ID: <20041126063048.GA10161@petdance.com>

[ 23549]
Document the interaction of PERL_USE_SAVE_PUTENV and
PL_use_safe_putenv, based on text by Stas Bekman

[ 23550]
Clarify the return values of pos, particularly 0 and undef, as
suggested by Stas Bekman
p4raw-link: @23550 on //depot/perl: b17c04f34c21c46addcb48d31ee352efe59be622
p4raw-link: @23549 on //depot/perl: 575e1338b8c2d1828cc5b364a6c4e723163fec93
p4raw-link: @23546 on //depot/perl: c00253d55e3afc04b4e470781703e82287f1eef6

p4raw-id: //depot/maint-5.8/perl@23551
p4raw-integrated: from //depot/perl@23540 'copy in' ext/B/B/Lint.pm
	(@20686..) 'merge in' pod/perlfunc.pod (@23345..) INSTALL
	(@23475..)

3 files changed, 31 insertions, 12 deletions

diff --git a/INSTALL b/INSTALL
index 1747b75c83..886bf54b54 100644
--- a/INSTALL
+++ b/INSTALL
@@ -657,6 +657,19 @@ architecture-dependent library for your -DDEBUGGING version of perl.
 You can do this by changing all the *archlib* variables in config.sh to
 point to your new architecture-dependent library.
 
+=head3 Environment access
+
+Perl often needs to write to the program's environment, such as when C<%ENV>
+is assigned to. Many implementations of the C library function C<putenv()>
+leak memory, so where possible perl will manipulate the environment directly
+to avoid these leaks. The default is now to perform direct manipulation
+whenever perl is running as a stand alone interpreter, and to call the safe
+but potentially leaky C<putenv()> function when the perl interpreter is
+embedded in another application. You can force perl to always use C<putenv()>
+by compiling with -DPERL_USE_SAVE_PUTENV. You can force an embedded perl to
+use direct manipulation by setting C<PL_use_safe_putenv = 0;> after the
+C<perl_construct()> call.
+
 =head2 Installation Directories
 
 The installation directories can all be changed by answering the
diff --git a/ext/B/B/Lint.pm b/ext/B/B/Lint.pm
index 1c08e8e0ea..3475bd2596 100644
--- a/ext/B/B/Lint.pm
+++ b/ext/B/B/Lint.pm
@@ -1,6 +1,6 @@
 package B::Lint;
 
-our $VERSION = '1.02';
+our $VERSION = '1.03';
 
 =head1 NAME
 
@@ -13,7 +13,7 @@ perl -MO=Lint[,OPTIONS] foo.pl
 =head1 DESCRIPTION
 
 The B::Lint module is equivalent to an extended version of the B<-w>
-option of B<perl>. It is named after the program B<lint> which carries
+option of B<perl>. It is named after the program F<lint> which carries
 out a similar process for C programs.
 
 =head1 OPTIONS AND LINT CHECKS
@@ -36,6 +36,7 @@ context. For example, both of the lines
 
     $foo = length(@bar);
     $foo = @bar;
+
 will elicit a warning. Using an explicit B<scalar()> silences the
 warning. For example,
 
@@ -63,15 +64,15 @@ This option warns whenever a bareword is implicitly quoted, but is also
 the name of a subroutine in the current package. Typical mistakes that it will
 trap are:
 
-	use constant foo => 'bar';
-	@a = ( foo => 1 );
-	$b{foo} = 2;
+    use constant foo => 'bar';
+    @a = ( foo => 1 );
+    $b{foo} = 2;
 
 Neither of these will do what a naive user would expect.
 
 =item B<dollar-underscore>
 
-This option warns whenever $_ is used either explicitly anywhere or
+This option warns whenever C<$_> is used either explicitly anywhere or
 as the implicit argument of a B<print> statement.
 
 =item B<private-names>
@@ -79,7 +80,7 @@ as the implicit argument of a B<print> statement.
 This option warns on each use of any variable, subroutine or
 method name that lives in a non-current package but begins with
 an underscore ("_"). Warnings aren't issued for the special case
-of the single character name "_" by itself (e.g. $_ and @_).
+of the single character name "_" by itself (e.g. C<$_> and C<@_>).
 
 =item B<undefined-subs>
 
@@ -92,8 +93,8 @@ mechanism.
 
 =item B<regexp-variables>
 
-This option warns whenever one of the regexp variables $', $& or
-$' is used. Any occurrence of any of these variables in your
+This option warns whenever one of the regexp variables C<$`>, C<$&> or C<$'>
+is used. Any occurrence of any of these variables in your
 program can slow your whole program down. See L<perlre> for
 details.
 
diff --git a/pod/perlfunc.pod b/pod/perlfunc.pod
index 9f3a1c236f..7e52c4121d 100644
--- a/pod/perlfunc.pod
+++ b/pod/perlfunc.pod
@@ -3747,9 +3747,14 @@ array in subroutines, just like C<shift>.
 =item pos
 
 Returns the offset of where the last C<m//g> search left off for the variable
-in question (C<$_> is used when the variable is not specified).  May be
-modified to change that offset.  Such modification will also influence
-the C<\G> zero-width assertion in regular expressions.  See L<perlre> and
+in question (C<$_> is used when the variable is not specified).  Note that
+0 is a valid match offset, while C<undef> indicates that the search position
+is reset (usually due to match failure, but can also be because no match has
+yet been performed on the scalar). C<pos> directly accesses the location used
+by the regexp engine to store the offset, so assigning to C<pos> will change
+that offset, and so will also influence the C<\G> zero-width assertion in
+regular expressions. Because a failed C<m//gc> match doesn't reset the offset,
+the return from C<pos> won't change either in this case.  See L<perlre> and
 L<perlop>.
 
 =item print FILEHANDLE LIST