XXX incomplete perlhacktips:

pod/perlhacktips.pod

@@ -453,6 +453,7 @@ functions are fully supported in modern compilers.
 Nevertheless, there are situations where a function won't do, and a
 macro is required.  One example is when a parameter can be any of
 several types.  A function has to be declared with a single explicit
+parameter type, so a macro may be called for.
 
 Or maybe the code involved is so trivial that a function would be just
 complicating overkill, such as when the macro simply creates a mnemonic
@@ -550,7 +551,7 @@ L<https://perlmonks.org/?node_id=11144355>.
 =head2 Portability problems
 
 The following are common causes of compilation and/or execution
-failures, not common to Perl as such.  The C FAQ is good bedtime
+failures, not specific to Perl as such.  The C FAQ is good bedtime
 reading.  Please test your changes with as many C compilers and
 platforms as possible; we will, anyway, and it's nice to save oneself
 from public embarrassment.
@@ -601,7 +602,7 @@ C<long long> is not even guaranteed to be any wider than C<long>.)
 
 Instead, use the definitions C<IV>, C<UV>, C<IVSIZE>, C<I32SIZE>, and
 so forth. Avoid things like C<I32> because they are B<not> guaranteed
-to be I<exactly> 32 bits, they are I<at least> 32 bits, nor are they
+to be I<exactly> 32 bits (they are I<at least> 32 bits), nor are they
 guaranteed to be C<int> or C<long>.  If you explicitly need 64-bit
 variables, use C<I64> and C<U64>.
 
@@ -879,7 +880,8 @@ intelligence, but for many types the right format is available as with
 either 'f' or '_f' suffix, for example:
 
    IVdf /* IV in decimal */
-   UVxf /* UV is hexadecimal */
+   UVxf /* UV in hexadecimal */
+   U32of /* A U32 in octal */ 
 
    printf("i = %"IVdf"\n", i); /* The IVdf is a string constant. */
 
@@ -1001,6 +1003,35 @@ you'll need to make the copy in a mortal scalar, like so
 
  SvPVX(sv_2mortal(newSVpv(volatile_string, 0)))
 
+Originally many of those wrappers returned
+subsequent calls to the same or related functions.  Perl has
+light-weight wrappers for some of these functions, and which propagate
+this issue on to the caller, you.  You'll have to save or finish using
+the result before calling the function again.  In some cases they aren't
+thread safe, and you'll need to save or use the value before any other
+thread can call that function.  You don't generally have control over
+when such a thread might want to use that function, so this can cause a
+race.  L<perlxs/Thread-aware system interfaces> has some information on
+such functions, and ways to cope.  But it may come down to not using a
+problematic function at all, or protecting its use with a mutex, and
+being sure that any other applications that might be running in another
+thread also use that mutex.  Until Perl 5.32, C<PerlEnv_getenv> was such
+a function, but now it returns a mortalized copy of the result.  But
+again, if someone is writing to the environment without using the mutex
+that HUH! C<> expects, they can memory in the C library, which could be
+overwritten at any time by another thread accessing the environment in
+some way, or on some platforms, by a subsequent C<PerlEnv_getenv> call.
+
+the interface to the
+
+environment variables that are in effect for the program.  Prior to Perl
+5.32, C<PerlEnv_getenv>, to get values from the environment, also was
+such a function.  But starting in that release, the return is a mortal
+copy of what is in the environment, so is safe to use in the remainder
+of the calling function, but needs to be copied if you want a stable
+value beyond that.
+
+
 =back
 
 =head2 Problematic System Interfaces