local (the keyword) has NOTHING to do with local variables. In Perl, you use my (the keyword) to declare local (i.e., lexically scoped, or 'lexical') variables.

The keyword local localizes a variable, whether it's named or anonymous or global (i.e., package variables, which are in the symbol table). To localize a variable is to stash away its value in such a way that exiting the enclosing scope will result in its being restored. For example: 

use vars qw( $x );      # a package global

$x = 'outer';

# this block:
{
  my $save_x = $x;      # localize $x by saving its  value
  $x = 'inner';         # change $x to hearts content

  some_sub( $x );       # some_sub() sees $x with value 'inner'

  $x = $save_x;         # restore original value just before exiting b
+lock
}

# is functionally identical to this block:
{
  local $x = 'inner';

  some_sub( $x );
}

# in both cases, some_sub() is called with the package global $x set
# to 'inner' and in both cases, the value of $x is restored when the
# block exits, except in the 'local' case, it is not necessary to
# explicitly restore $x

[download]

One example of its use is with the Perl global, $/. Often, (in a subroutine, for example) it is necessary to set $/ = undef;, but to do so may break code which assumes its default value. 

# need to 'slurp' in an entire file
{
  local $/ = undef;

  # (read the file, etc.)
}
# $/ is now restored to whatever it was before

[download]

Hopefully, this explains WHEN to use local.

Update: Whoops! I stand corrected (thanks, shotgunefx)! Starting with Perl 5.5, it became possible to localize arbitrary anonymous variables (e.g., local $obj->get_handle()->{some_property}->get_param("param1");). I never actually had a use for (and therefore never tried) localize a lexical; I suppose I just assumed that they could.

Apologies to all for suggesting that localizing a lexical was possible.

dmm

If you GIVE a man a fish you feed him for a day
But, TEACH him to fish and you feed him for a lifetime

In reply to Re(4) Whether to use local() by dmmiller2k
in thread Whether to use local() by jerrygarciuh

Title:
Use:  <p> text here (a paragraph) </p>
and:  <code> code here </code>
to format your post, it's "PerlMonks-approved HTML":


  • Posts are HTML formatted. Put <p> </p> tags around your paragraphs. Put <code> </code> tags around your code and data!
  • Titles consisting of a single word are discouraged, and in most cases are disallowed outright.
  • Read Where should I post X? if you're not absolutely sure you're posting in the right place.
  • Please read these before you post! —
  • Posts may use any of the Perl Monks Approved HTML tags:
    a, abbr, b, big, blockquote, br, caption, center, col, colgroup, dd, del, details, div, dl, dt, em, font, h1, h2, h3, h4, h5, h6, hr, i, ins, li, ol, p, pre, readmore, small, span, spoiler, strike, strong, sub, summary, sup, table, tbody, td, tfoot, th, thead, tr, tt, u, ul, wbr
  • You may need to use entities for some characters, as follows. (Exception: Within code tags, you can put the characters literally.)
            For:     Use:
    & &amp;
    < &lt;
    > &gt;
    [ &#91;
    ] &#93;
  • Link using PerlMonks shortcuts! What shortcuts can I use for linking?
  • See Writeup Formatting Tips and other pages linked from there for more info.