* Note that unlink sets $! on failure.

The docs to unlink didn't explicitly note that it set $! on
failure, unlike the docs on some other system calls do.

While I was in there, I cleansed the entry a little and
added an example of unlinking files one-by-one to find
the ones that fail.

Modern Perl fix: let's call a glob a glob() and not a <*>.

This problem was noted on the Perl Beginner's list:

http://www.nntp.perl.org/group/perl.beginners/2009/11/msg110062.html

diff --git a/pod/perlfunc.pod b/pod/perlfunc.pod
index d8d554a..ddb5bce 100644 (file)
--- a/pod/perlfunc.pod
+++ b/pod/perlfunc.pod
@@ -6858,20 +6858,29 @@ X<unlink> X<delete> X<remove> X<rm> X<del>
 
 =item unlink
 
-Deletes a list of files.  Returns the number of files successfully
-deleted.
+Deletes a list of files. On success, it returns the number of files
+it successfully deleted. On failure, it returns false and sets C<$!>
+(errno):
 
-    $cnt = unlink 'a', 'b', 'c';
+    my $unlinked = unlink 'a', 'b', 'c';
     unlink @goners;
-    unlink <*.bak>;
+    unlink glob "*.bak";
 
-Note: C<unlink> will not attempt to delete directories unless you are superuser
-and the B<-U> flag is supplied to Perl.  Even if these conditions are
-met, be warned that unlinking a directory can inflict damage on your
-filesystem.  Finally, using C<unlink> on directories is not supported on 
-many operating systems.  Use C<rmdir> instead.
+On error, C<unlink> will not tell you which files it could not remove.
+If you care about the files you could not remove, try them one
+at a time:
 
-If LIST is omitted, uses C<$_>.
+     foreach my $file ( @goners ) {
+         unlink $file or warn "Could not unlink $file: $!";
+         }
+
+Note: C<unlink> will not attempt to delete directories unless you are
+superuser and the B<-U> flag is supplied to Perl. Even if these
+conditions are met, be warned that unlinking a directory can inflict
+damage on your filesystem.  Finally, using C<unlink> on directories is
+not supported on many operating systems.  Use C<rmdir> instead.
+
+If LIST is omitted, C<unlink> uses C<$_>.
 
 =item unpack TEMPLATE,EXPR
 X<unpack>