Better options for rsync.

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

diff --git a/pod/perlguts.pod b/pod/perlguts.pod
index 1738742..2f75cff 100644 (file)
--- a/pod/perlguts.pod
+++ b/pod/perlguts.pod
@@ -1317,6 +1317,21 @@ destination starting points.  Perl will move, copy, or zero out C<number>
 instances of the size of the C<type> data structure (using the C<sizeof>
 function).
 
+Here is a handy table of equivalents between ordinary C and Perl's
+memory abstraction layer:
+
+    Instead Of:                Use:
+
+    malloc                     New
+    calloc                     Newz
+    realloc                    Renew
+    memcopy                    Copy
+    memmove                    Move
+    free                       Safefree
+    strdup                     savepv
+    strndup                    savepvn (Hey, strndup doesn't exist!)
+    memcpy/*(struct foo *)    StructCopy
+
 =head2 PerlIO
 
 The most recent development releases of Perl has been experimenting with
@@ -1862,6 +1877,50 @@ This function isn't exported out of the Perl core.
 If you edit F<embed.pl>, you will need to run C<make regen_headers> to
 force a rebuild of F<embed.h> and other auto-generated files.
 
+=head2 Formatted Printing of IVs, UVs, and NVs
+
+If you are printing IVs, UVs, or NVS instead of the stdio(3) style
+formatting codes like C<%d>, C<%ld>, C<%f>, you should use the
+following macros for portability
+
+       IVdf            IV in decimal
+       UVuf            UV in decimal
+       UVof            UV in octal
+       UVxf            UV in hexadecimal
+       NVef            NV %e-like
+       NVff            NV %f-like
+       NVgf            NV %g-like
+
+These will take care of 64-bit integers and long doubles.
+For example:
+
+       printf("IV is %"IVdf"\n", iv);
+
+The IVdf will expand to whatever is the correct format for the IVs.
+
+If you are printing addresses of pointers, use UVxf combined
+with PTR2UV(), do not use %lx or %p.
+
+=head2 Pointer-To-Integer and Integer-To-Pointer
+
+Because pointer size does not necessarily equal integer size,
+use the follow macros to do it right.
+
+       PTR2UV(pointer)
+       PTR2IV(pointer)
+       PTR2NV(pointer)
+       INT2PTR(pointertotype, integer)
+
+For example:
+
+       IV  iv = ...;
+       SV *sv = INT2PTR(SV*, iv);
+
+and
+
+       AV *av = ...;
+       UV  uv = PTR2UV(av);
+
 =head2 Source Documentation
 
 There's an effort going on to document the internal functions and
@@ -1935,7 +1994,7 @@ whether the current character in a string is valid UTF8.
 As mentioned above, UTF8 uses a variable number of bytes to store a
 character. Characters with values 1...128 are stored in one byte, just
 like good ol' ASCII. Character 129 is stored as C<v194.129>; this
-contines up to character 191, which is C<v194.191>. Now we've run out of
+continues up to character 191, which is C<v194.191>. Now we've run out of
 bits (191 is binary C<10111111>) so we move on; 192 is C<v195.128>. And
 so it goes on, moving to three bytes at character 2048.
 
@@ -2047,12 +2106,12 @@ However, you must not do this, for example:
         sv_utf8_upgrade(left);
 
 If you do this in a binary operator, you will actually change one of the
-strings that came into the operator, and, while it shouldn't be noticable
+strings that came into the operator, and, while it shouldn't be noticeable
 by the end user, it can cause problems.
 
 Instead, C<bytes_to_utf8> will give you a UTF8-encoded B<copy> of its
 string argument. This is useful for having the data available for
-comparisons and so on, without harming the orginal SV. There's also
+comparisons and so on, without harming the original SV. There's also
 C<utf8_to_bytes> to go the other way, but naturally, this will fail if
 the string contains any characters above 255 that can't be represented
 in a single byte.