document are not intended for public use, and should NOT be used under any
circumstances.
-If you use one of the undocumented functions below, you may wish to consider
-creating and submitting documentation
-for it. If your patch is accepted, this
-will indicate that the interface is stable (unless it is explicitly marked
-otherwise).
+If you feel you need to use one of these functions, first send email to
+L<perl5-porters@perl.org|mailto:perl5-porters@perl.org>. It may be
+that there is a good reason for the function not being documented, and it
+should be removed from this list; or it may just be that no one has gotten
+around to documenting it. In the latter case, you will be asked to submit a
+patch to document the function. Once your patch is accepted, it will indicate
+that the interface is stable (unless it is explicitly marked otherwise) and
+usable by you.
=over
all. For these reasons, blindly using functions listed in proto.h is to be
avoided when writing extensions.
+In Perl, unlike C, a string of characters may generally contain embedded
+C<NUL> characters. Sometimes in the documentation a Perl string is referred
+to as a "buffer" to distinguish it from a C string, but sometimes they are
+both just referred to as strings.
+
Note that all Perl API global variables must be referenced with the C<PL_>
prefix. Again, those not listed here are not to be used by extension writers,
and can be changed or removed without notice; same with macros.
And documentation and comments may still use the term ASCII, when
sometimes in fact the entire range from 0 - 255 is meant.
-Note that Perl can be compiled and run under EBCDIC (See L<perlebcdic>)
-or ASCII. Most of the documentation (and even comments in the code)
+Note that Perl can be compiled and run under either ASCII or EBCDIC (See
+L<perlebcdic>). Most of the documentation (and even comments in the code)
ignore the EBCDIC possibility.
For almost all purposes the differences are transparent.
As an example, under EBCDIC,
(and variants of that name, including in function names),
it also (essentially transparently) means C<UTF-EBCDIC>.
But the ordinals of characters differ between ASCII, EBCDIC, and
-the UTF- encodings, and a string encoded in UTF-EBCDIC may occupy more bytes
-than in UTF-8.
+the UTF- encodings, and a string encoded in UTF-EBCDIC may occupy a different
+number of bytes than in UTF-8.
The listing below is alphabetical, case insensitive.
https://perl5.git.perl.org / perl5.git / blobdiff