Warn against using bare v-strings as IP addresses

(okay if using the wrappers from Socket)

p4raw-id: //depot/perl@11974

diff --git a/pod/perldata.pod b/pod/perldata.pod
index ffb47f0..968588d 100644 (file)
--- a/pod/perldata.pod
+++ b/pod/perldata.pod
@@ -333,13 +333,13 @@ anything more complicated in the subscript will be interpreted as
 an expression.
 
 A literal of the form C<v1.20.300.4000> is parsed as a string composed
-of characters with the specified ordinals.  This provides an alternative,
-more readable way to construct strings, rather than use the somewhat less
-readable interpolation form C<"\x{1}\x{14}\x{12c}\x{fa0}">.  This is useful
-for representing Unicode strings, and for comparing version "numbers"
-using the string comparison operators, C<cmp>, C<gt>, C<lt> etc.
-If there are two or more dots in the literal, the leading C<v> may be
-omitted.
+of characters with the specified ordinals.  This form, known as
+v-strings, provides an alternative, more readable way to construct
+strings, rather than use the somewhat less readable interpolation form
+C<"\x{1}\x{14}\x{12c}\x{fa0}">.  This is useful for representing
+Unicode strings, and for comparing version "numbers" using the string
+comparison operators, C<cmp>, C<gt>, C<lt> etc.  If there are two or
+more dots in the literal, the leading C<v> may be omitted.
 
     print v9786;              # prints UTF-8 encoded SMILEY, "\x{263a}"
     print v102.111.111;       # prints "foo"
@@ -348,6 +348,8 @@ omitted.
 Such literals are accepted by both C<require> and C<use> for
 doing a version check.  The C<$^V> special variable also contains the
 running Perl interpreter's version in this form.  See L<perlvar/$^V>.
+Note that using the v-strings for IPv4 addresses is not portable unless
+you also use the inet_aton()/inet_ntoa() routines of the Socket package.
 
 The special literals __FILE__, __LINE__, and __PACKAGE__
 represent the current filename, line number, and package name at that

diff --git a/pod/perlport.pod b/pod/perlport.pod
index 9abaff6..f8f17a1 100644 (file)
--- a/pod/perlport.pod
+++ b/pod/perlport.pod
@@ -423,6 +423,14 @@ simple, platform-independent mailing.
 The Unix System V IPC (C<msg*(), sem*(), shm*()>) is not available
 even on all Unix platforms.
 
+Do not use either the bare result of C<pack("N", 10, 20, 30, 40)
+or bare v-strings (such as C<v10.20.30.40>) or the to represent
+IPv4 addresses: both forms just pack the four bytes into network order.
+That this would be equal to the C language C<in_addr> struct (which is
+what the socket code internally uses) is not guaranteed.  To be
+portable use the routines of the Socket extension, such as
+C<inet_aton()>, C<inet_ntoa()>, and C<sockaddr_in()>.
+
 The rule of thumb for portable code is: Do it all in portable Perl, or
 use a module (that may internally implement it with platform-specific
 code, but expose a common interface).