There was no nice way of getting in UTF-8 filenames:

now one can use in the (new) three-arg form of readdir()
and in File::Glob import a ":utf8" to transparently accept
the filenames as Unicode.  Note that only :utf8 is supported,
not fancier stuff like :encoding(foobar)

p4raw-id: //depot/perl@15776

5 files changed, 33 insertions, 0 deletions

diff --git a/pod/perldelta.pod b/pod/perldelta.pod
index ab644bf2b9..37c2a31674 100644
--- a/pod/perldelta.pod
+++ b/pod/perldelta.pod
@@ -319,6 +319,12 @@ contain the strings 'UTF-8' or 'UTF8' (case-insensitive matching),
 the default encoding of your STDIN, STDOUT, and STDERR, and of
 B<any subsequent file open>, is UTF-8.
 
+=item *
+
+If your filesystem supports returning UTF-8 encoded filenames,
+it is possible to make Perl to understand that the filenames
+returned by readdir() and glob() are in Unicode.
+
 =back
 
 =head2 Safe Signals
diff --git a/pod/perldiag.pod b/pod/perldiag.pod
index f22aa80f75..ee3c617be8 100644
--- a/pod/perldiag.pod
+++ b/pod/perldiag.pod
@@ -3716,6 +3716,12 @@ what you are doing you can turn off this warning by C<no warnings 'utf8';>.
 (F) There are no byte-swapping functions for a machine with this byte
 order.
 
+=item Unknown discipline '%s'
+
+(F) You specified an unknown I/O discipline.  See L<open> for valid
+filehandle disciplines and L<perlfunc/opendir> for valid directory
+handle disciplines.
+
 =item Unknown "re" subpragma '%s' (known ones are: %s)
 
 You tried to use an unknown subpragma of the "re" pragma.
diff --git a/pod/perlfunc.pod b/pod/perlfunc.pod
index d20851f53f..c04cc482c8 100644
--- a/pod/perlfunc.pod
+++ b/pod/perlfunc.pod
@@ -3024,12 +3024,19 @@ them, and automatically close whenever and however you leave that scope:
 
 See L</seek> for some details about mixing reading and writing.
 
+=item opendir DIRHANDLE,MODE,EXPR
+
 =item opendir DIRHANDLE,EXPR
 
 Opens a directory named EXPR for processing by C<readdir>, C<telldir>,
 C<seekdir>, C<rewinddir>, and C<closedir>.  Returns true if successful.
 DIRHANDLEs have their own namespace separate from FILEHANDLEs.
 
+In three-argument form the middle argument may be C<:utf8> to force
+the filenames returned by readdir() to be in UTF-8 encoding of Unicode.
+This naturally works only if your filesystem returns UTF-8 filenames.
+The encoding pragma affects this feature, see L<encoding>.
+
 =item ord EXPR
 
 =item ord
@@ -3728,6 +3735,10 @@ C<chdir> there, it would have been testing the wrong file.
     @dots = grep { /^\./ && -f "$some_dir/$_" } readdir(DIR);
     closedir DIR;
 
+In some filesystems it is possible to return UTF-8 encoded filenames.
+To get readdir() to return such filenames, you must use C<:utf8> with
+the three-argument form of opendir(), see L</opendir>.
+
 =item readline EXPR
 
 Reads from the filehandle whose typeglob is contained in EXPR.  In scalar
diff --git a/pod/perlunicode.pod b/pod/perlunicode.pod
index 26e704a63e..d6367004a3 100644
--- a/pod/perlunicode.pod
+++ b/pod/perlunicode.pod
@@ -20,6 +20,11 @@ Other encodings can be converted to perl's encoding on input, or from
 perl's encoding on output by use of the ":encoding(...)" layer.
 See L<open>.
 
+In some filesystems (for example Microsoft NTFS and Apple HFS+) the
+filenames are in UTF-8 .  By using opendir() and File::Glob you can
+make readdir() and glob() to return the filenames as Unicode, see
+L<perlfunc/opendir> and L<File::Glob> for details.
+
 To mark the Perl source itself as being in a particular encoding,
 see L<encoding>.
 
diff --git a/pod/perluniintro.pod b/pod/perluniintro.pod
index dd3064f6bf..736a0e2d0a 100644
--- a/pod/perluniintro.pod
+++ b/pod/perluniintro.pod
@@ -407,6 +407,11 @@ If you run this code twice, the contents of the F<file> will be twice
 UTF-8 encoded.  A C<use open ':utf8'> would have avoided the bug, or
 explicitly opening also the F<file> for input as UTF-8.
 
+In some filesystems (for example Microsoft NTFS and Apple HFS+) the
+filenames are in UTF-8 .  By using opendir() and File::Glob you can
+make readdir() and glob() to return the filenames as Unicode, see
+L<perlfunc/opendir> and L<File::Glob> for details.
+
 B<NOTE>: the C<:utf8> and C<:encoding> features work only if your
 Perl has been built with the new "perlio" feature.  Almost all 
 Perl 5.8 platforms do use "perlio", though: you can see whether