This is a live mirror of the Perl 5 development currently hosted at https://github.com/perl/perl5
perlapi: Clarify some instances where NUL is or isn't permitted
authorKarl Williamson <khw@cpan.org>
Mon, 5 May 2014 00:58:51 +0000 (18:58 -0600)
committerKarl Williamson <khw@cpan.org>
Fri, 30 May 2014 22:13:46 +0000 (16:13 -0600)
Some functions that take a string/length pair can have embedded NULs and
don't have to be NUL terminated; others are the opposite.  This adds
text to clarify the issue.

handy.h
sv.c
sv.h
util.c

diff --git a/handy.h b/handy.h
index 5249b31..e4e5292 100644 (file)
--- a/handy.h
+++ b/handy.h
@@ -304,19 +304,20 @@ typedef U64TYPE U64;
 =head1 SV-Body Allocation
 
 =for apidoc Ama|SV*|newSVpvs|const char* s
-Like C<newSVpvn>, but takes a literal string instead of a string/length pair.
+Like C<newSVpvn>, but takes a literal C<NUL>-terminated string instead of a
+string/length pair.
 
 =for apidoc Ama|SV*|newSVpvs_flags|const char* s|U32 flags
-Like C<newSVpvn_flags>, but takes a literal string instead of a string/length
-pair.
+Like C<newSVpvn_flags>, but takes a literal C<NUL>-terminated string instead of
+a string/length pair.
 
 =for apidoc Ama|SV*|newSVpvs_share|const char* s
-Like C<newSVpvn_share>, but takes a literal string instead of a string/length
-pair and omits the hash parameter.
+Like C<newSVpvn_share>, but takes a literal C<NUL>-terminated string instead of
+a string/length pair and omits the hash parameter.
 
 =for apidoc Am|void|sv_catpvs_flags|SV* sv|const char* s|I32 flags
-Like C<sv_catpvn_flags>, but takes a literal string instead of a
-string/length pair.
+Like C<sv_catpvn_flags>, but takes a literal C<NUL>-terminated string instead
+of a string/length pair.
 
 =for apidoc Am|void|sv_catpvs_nomg|SV* sv|const char* s
 Like C<sv_catpvn_nomg>, but takes a literal string instead of a
@@ -343,7 +344,8 @@ string/length pair.
 =head1 Memory Management
 
 =for apidoc Ama|char*|savepvs|const char* s
-Like C<savepvn>, but takes a literal string instead of a string/length pair.
+Like C<savepvn>, but takes a literal C<NUL>-terminated string instead of a
+string/length pair.
 
 =for apidoc Ama|char*|savesharedpvs|const char* s
 A version of C<savepvs()> which allocates the duplicate string in memory
diff --git a/sv.c b/sv.c
index bde719b..76ca0d9 100644 (file)
--- a/sv.c
+++ b/sv.c
@@ -8864,7 +8864,8 @@ Perl_sv_newmortal(pTHX)
 /*
 =for apidoc newSVpvn_flags
 
-Creates a new SV and copies a string into it.  The reference count for the
+Creates a new SV and copies a string (which may contain C<NUL> (C<\0>)
+characters) into it.  The reference count for the
 SV is set to 1.  Note that if C<len> is zero, Perl will create a zero length
 string.  You are responsible for ensuring that the source string is at least
 C<len> bytes long.  If the C<s> argument is NULL the new SV will be undefined.
@@ -8938,9 +8939,13 @@ Perl_sv_2mortal(pTHX_ SV *const sv)
 /*
 =for apidoc newSVpv
 
-Creates a new SV and copies a string into it.  The reference count for the
+Creates a new SV and copies a string (which may contain C<NUL> (C<\0>)
+characters) into it.  The reference count for the
 SV is set to 1.  If C<len> is zero, Perl will compute the length using
-strlen().  For efficiency, consider using C<newSVpvn> instead.
+strlen(), (which means if you use this option, that C<s> can't have embedded
+C<NUL> characters and has to have a terminating C<NUL> byte).
+
+For efficiency, consider using C<newSVpvn> instead.
 
 =cut
 */
diff --git a/sv.h b/sv.h
index 003112c..abcfbb6 100644 (file)
--- a/sv.h
+++ b/sv.h
@@ -2163,7 +2163,8 @@ struct clone_params {
 /*
 =for apidoc Am|SV*|newSVpvn_utf8|NULLOK const char* s|STRLEN len|U32 utf8
 
-Creates a new SV and copies a string into it.  If utf8 is true, calls
+Creates a new SV and copies a string (which may contain C<NUL> (C<\0>)
+characters) into it.  If utf8 is true, calls
 C<SvUTF8_on> on the new SV.  Implemented as a wrapper around C<newSVpvn_flags>.
 
 =cut
diff --git a/util.c b/util.c
index 935d7e0..6e71fa2 100644 (file)
--- a/util.c
+++ b/util.c
@@ -1004,8 +1004,9 @@ Perl_foldEQ_locale(const char *s1, const char *s2, I32 len)
 
 Perl's version of C<strdup()>.  Returns a pointer to a newly allocated
 string which is a duplicate of C<pv>.  The size of the string is
-determined by C<strlen()>.  The memory allocated for the new string can
-be freed with the C<Safefree()> function.
+determined by C<strlen()>, which means it may not contain embedded C<NUL>
+characters and must have a trailing C<NUL>.  The memory allocated for the new
+string can be freed with the C<Safefree()> function.
 
 On some platforms, Windows for example, all allocated memory owned by a thread
 is deallocated when that thread ends.  So if you need that not to happen, you