Doc tweaks.
[p5sagit/p5-mst-13.2.git] / pod / perlfunc.pod
index 49efec6..bfb91bb 100644 (file)
@@ -172,7 +172,7 @@ C<untie>, C<use>
 
 C<accept>, C<bind>, C<connect>, C<getpeername>, C<getsockname>,
 C<getsockopt>, C<listen>, C<recv>, C<send>, C<setsockopt>, C<shutdown>,
-C<sockatmark>, C<socket>, C<socketpair>
+C<socket>, C<socketpair>
 
 =item System V interprocess communication functions
 
@@ -234,7 +234,7 @@ C<msgsnd>, C<open>, C<pipe>, C<readlink>, C<rename>, C<select>, C<semctl>,
 C<semget>, C<semop>, C<setgrent>, C<sethostent>, C<setnetent>,
 C<setpgrp>, C<setpriority>, C<setprotoent>, C<setpwent>,
 C<setservent>, C<setsockopt>, C<shmctl>, C<shmget>, C<shmread>,
-C<shmwrite>, C<sockatmark>, C<socket>, C<socketpair>,
+C<shmwrite>, C<socket>, C<socketpair>,
 C<stat>, C<symlink>, C<syscall>, C<sysopen>, C<system>,
 C<times>, C<truncate>, C<umask>, C<unlink>,
 C<utime>, C<wait>, C<waitpid>
@@ -457,7 +457,7 @@ name of the filehandle.
 DISCIPLINE can be either of C<:raw> for binary mode or C<:crlf> for
 "text" mode.  If the DISCIPLINE is omitted, it defaults to C<:raw>.
 Returns true on success, C<undef> on failure.  To mark FILEHANDLE as
-UTF-8, use C<:utf8>, and to mark the as bytes, use C<:bytes>.
+UTF-8, use C<:utf8>, and to mark it as bytes, use C<:bytes>.
 
 The C<:raw> are C<:clrf>, and any other directives of the form
 C<:...>, are called I/O I<disciplines>.  The C<open> pragma can be
@@ -554,11 +554,13 @@ C<$is_require> are set: C<$is_require> is true if the frame is created by a
 C<require> or C<use> statement, $evaltext contains the text of the
 C<eval EXPR> statement.  In particular, for an C<eval BLOCK> statement,
 $filename is C<(eval)>, but $evaltext is undefined.  (Note also that
-each C<use> statement creates a C<require> frame inside an C<eval EXPR>)
-frame.  C<$hasargs> is true if a new instance of C<@_> was set up for the
-frame.  C<$hints> and C<$bitmask> contain pragmatic hints that the caller
-was compiled with.  The C<$hints> and C<$bitmask> values are subject to
-change between versions of Perl, and are not meant for external use.
+each C<use> statement creates a C<require> frame inside an C<eval EXPR>
+frame.)  $subroutine may also be C<(unknown)> if this particular
+subroutine happens to have been deleted from the symbol table.
+C<$hasargs> is true if a new instance of C<@_> was set up for the frame.
+C<$hints> and C<$bitmask> contain pragmatic hints that the caller was
+compiled with.  The C<$hints> and C<$bitmask> values are subject to change
+between versions of Perl, and are not meant for external use.
 
 Furthermore, when called from within the DB package, caller returns more
 detailed information: it sets the list variable C<@DB::args> to be the
@@ -2810,7 +2812,13 @@ opens a filehandle to an anonymous temporary file.
 
 File handles can be opened to "in memory" files held in Perl scalars via:
 
-    open($fh,'>', \$variable) || ..
+    open($fh, '>', \$variable) || ..
+
+Though if you try to re-open C<STDOUT> or C<STDERR> as an "in memory"
+file, you have to close it first:
+
+    close STDOUT;
+    open STDOUT, '>', \$variable or die "Can't open STDOUT: $!";
 
 Examples:
 
@@ -4424,26 +4432,6 @@ help.
 
 See also the POSIX module's C<pause> function.
 
-=item sockatmark SOCKET
-
-Returns true if the socket is positioned at the out-of-band mark
-(also known as the urgent data mark), false otherwise.  Use right
-after reading from the socket.
-
-Not available directly, one has to import the function from
-the IO::Socket extension
-
-    use IO::Socket 'sockatmark';
-
-Even this doesn't guarantee that sockatmark() really is available,
-though, because sockatmark() is a relatively recent addition to
-the family of socket functions.  If it is unavailable, attempt to
-use it will fail
-
-       IO::Socket::atmark not implemented on this architecture ...
-
-See also L<IO::Socket>.
-
 =item socket SOCKET,DOMAIN,TYPE,PROTOCOL
 
 Opens a socket of the specified kind and attaches it to filehandle
@@ -4616,12 +4604,6 @@ Examples:
     use sort '_mergesort';  # note discouraging _
     @new = sort { substr($a, 3, 5) cmp substr($b, 3, 5) } @old;
 
-    # Similar to the previous example, but demand stability as well
-    # Because of the way quicksort is "stabilized", this combination
-    # is not threadsafe
-    use sort qw( _quicksort stable );
-    @new = sort { substr($a, 3, 5) cmp substr($b, 3, 5) } @old;
-
 If you're using strict, you I<must not> declare $a
 and $b as lexicals.  They are package globals.  That means
 if you're in the C<main> package and type
@@ -5658,6 +5640,9 @@ specified length.  Produces a fatal error if truncate isn't implemented
 on your system.  Returns true if successful, the undefined value
 otherwise.
 
+The behavior is undefined if LENGTH is greater than the length of the
+file.
+
 =item uc EXPR
 
 =item uc