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

1 files changed, 11 insertions, 0 deletions

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