X-Git-Url: http://git.shadowcat.co.uk/gitweb/gitweb.cgi?a=blobdiff_plain;f=pod%2Fperlfunc.pod;h=b918cac80c86293d26e6a28469bcc77313458217;hb=938c8732ceb115a707f725327a631eb35319ba87;hp=b2c67763f53bcb85c752a5b3f930a20ee4969e6a;hpb=8b0ac1d72e8a6530ddcafe41734c2fd10d6cbe5a;p=p5sagit%2Fp5-mst-13.2.git

diff --git a/pod/perlfunc.pod b/pod/perlfunc.pod
index b2c6776..b918cac 100644
--- a/pod/perlfunc.pod
+++ b/pod/perlfunc.pod
@@ -2097,7 +2097,34 @@ IPs that the connection might have come in on.
 
 =item getsockopt SOCKET,LEVEL,OPTNAME
 
-Returns the socket option requested, or undef if there is an error.
+Queries the option named OPTNAME associated with SOCKET at a given LEVEL.
+Options may exist at multiple protocol levels depending on the socket
+type, but at least the uppermost socket level SOL_SOCKET (defined in the
+C<Socket> module) will exist. To query options at another level the
+protocol number of the appropriate protocol controlling the option
+should be supplied. For example, to indicate that an option is to be
+interpreted by the TCP protocol, LEVEL should be set to the protocol
+number of TCP, which you can get using getprotobyname.
+
+The call returns a packed string representing the requested socket option,
+or C<undef> if there is an error (the error reason will be in $!). What
+exactly is in the packed string depends in the LEVEL and OPTNAME, consult
+your system documentation for details. A very common case however is that
+the option is an integer, in which case the result will be an packed
+integer which you can decode using unpack with the C<i> (or C<I>) format.
+
+An example testing if Nagle's algorithm is turned on on a socket:
+
+    use Socket;
+
+    defined(my $tcp = getprotobyname("tcp"))
+	or die "Could not determine the protocol number for tcp";
+    # my $tcp = Socket::IPPROTO_TCP; # Alternative
+    my $packed = getsockopt($socket, $tcp, Socket::TCP_NODELAY)
+	or die "Could not query TCP_NODELAY SOCKEt option: $!";
+    my $nodelay = unpack("I", $packed);
+    print "Nagle's algorithm is turned ", $nodelay ? "off\n" : "on\n";
+
 
 =item glob EXPR
 
@@ -2908,7 +2935,9 @@ works for symmetry, but you really should consider writing something
 to the temporary file first.  You will need to seek() to do the
 reading.
 
-File handles can be opened to "in memory" files held in Perl scalars via:
+Since v5.8.0, perl has built using PerlIO by default.  Unless you've
+changed this (ie Configure -Uuseperlio), you can open file handles to
+"in memory" files held in Perl scalars via:
 
     open($fh, '>', \$variable) || ..
 
@@ -2971,6 +3000,8 @@ Examples:
 	}
     }
 
+See L<perliol/> for detailed info on PerlIO.
+
 You may also, in the Bourne shell tradition, specify an EXPR beginning
 with C<< '>&' >>, in which case the rest of the string is interpreted
 as the name of a filehandle (or file descriptor, if numeric) to be
@@ -5719,7 +5750,7 @@ using the C<|>-operator.
 
 Some of the most common values are C<O_RDONLY> for opening the file in
 read-only mode, C<O_WRONLY> for opening the file in write-only mode,
-and C<O_RDWR> for opening the file in read-write mode, and.
+and C<O_RDWR> for opening the file in read-write mode.
 
 For historical reasons, some values work on almost every system
 supported by perl: zero means read-only, one means write-only, and two
@@ -5736,10 +5767,15 @@ process's current C<umask>.
 
 In many systems the C<O_EXCL> flag is available for opening files in
 exclusive mode.  This is B<not> locking: exclusiveness means here that
-if the file already exists, sysopen() fails.  The C<O_EXCL> wins
-C<O_TRUNC>.
-
-Sometimes you may want to truncate an already-existing file: C<O_TRUNC>.
+if the file already exists, sysopen() fails.  C<O_EXCL> may not work
+on network filesystems, and has no effect unless the C<O_CREAT> flag
+is set as well.  Setting C<O_CREAT|O_EXCL> prevents the file from
+being opened if it is a symbolic link.  It does not protect against
+symbolic links in the file's path.
+
+Sometimes you may want to truncate an already-existing file.  This
+can be done using the C<O_TRUNC> flag.  The behavior of
+C<O_TRUNC> with C<O_RDONLY> is undefined.
 
 You should seldom if ever use C<0644> as argument to C<sysopen>, because
 that takes away the user's option to have a more permissive umask.