Clarification: use encoding cannot be used to

[p5sagit/p5-mst-13.2.git] / pod / perlapi.pod

diff --git a/pod/perlapi.pod b/pod/perlapi.pod
index 41d2373..89894fc 100644 (file)
--- a/pod/perlapi.pod
+++ b/pod/perlapi.pod
@@ -3664,14 +3664,18 @@ Found in file sv.c
 
 =item sv_recode_to_utf8
 
-If PL_encoding is set you can call this to recode the pv of the sv.
-The PL_encoding is assumed to be an Encode object, on entry the pv is assumed
-to be octets in that encoding, and the sv will be converted into Unicode
-(and UTF-8).
+The encoding is assumed to be an Encode object, on entry the PV
+of the sv is assumed to be octets in that encoding, and the sv
+will be converted into Unicode (and UTF-8).
 
-If PL_encoding is not an Encode object, things will go boom.
+If the sv already is UTF-8 (or if it is not POK), or if the encoding
+is not a reference, nothing is done to the sv.  If the encoding is not
+an C<Encode::XS> Encoding object, bad things will happen.
+(See F<lib/encoding.pm> and L<Encode>).
 
-       void    sv_recode_to_utf8(SV*)
+The PV of the sv is returned.
+
+       char*   sv_recode_to_utf8(SV* sv, SV *encoding)
 
 =for hackers
 Found in file sv.c