Document sockatmark() some.

p4raw-id: //depot/perl@9376

4 files changed, 45 insertions, 14 deletions

diff --git a/pod/perldiag.pod b/pod/perldiag.pod
index 122f5ea144..0bcf180802 100644
--- a/pod/perldiag.pod
+++ b/pod/perldiag.pod
@@ -1738,6 +1738,11 @@ strange for a machine that supports C.
 (W unopened) You tried ioctl() on a filehandle that was never opened.
 Check you control flow and number of arguments.
 
+=item IO::Socket::atmark not implemented on this architecture
+
+(F) Your machine doesn't implement the sockatmark() functionality,
+neither as a system call or an ioctl call (SIOCATMARK).
+
 =item `%s' is not a code reference
 
 (W) The second (fourth, sixth, ...) argument of overload::constant needs
diff --git a/pod/perlfunc.pod b/pod/perlfunc.pod
index 7aaeaf3d3b..aafc1976aa 100644
--- a/pod/perlfunc.pod
+++ b/pod/perlfunc.pod
@@ -172,7 +172,7 @@ C<untie>, C<use>
 
 C<accept>, C<bind>, C<connect>, C<getpeername>, C<getsockname>,
 C<getsockopt>, C<listen>, C<recv>, C<send>, C<setsockopt>, C<shutdown>,
-C<socket>, C<socketpair>
+C<sockatmark>, C<socket>, C<socketpair>
 
 =item System V interprocess communication functions
 
@@ -234,8 +234,9 @@ C<msgsnd>, C<open>, C<pipe>, C<readlink>, C<rename>, C<select>, C<semctl>,
 C<semget>, C<semop>, C<setgrent>, C<sethostent>, C<setnetent>,
 C<setpgrp>, C<setpriority>, C<setprotoent>, C<setpwent>,
 C<setservent>, C<setsockopt>, C<shmctl>, C<shmget>, C<shmread>,
-C<shmwrite>, C<socket>, C<socketpair>, C<stat>, C<symlink>, C<syscall>,
-C<sysopen>, C<system>, C<times>, C<truncate>, C<umask>, C<unlink>,
+C<shmwrite>, C<sockatmark>, C<socket>, C<socketpair>,
+C<stat>, C<symlink>, C<syscall>, C<sysopen>, C<system>,
+C<times>, C<truncate>, C<umask>, C<unlink>,
 C<utime>, C<wait>, C<waitpid>
 
 For more information about the portability of these functions, see
@@ -4155,6 +4156,26 @@ may also help.
 
 See also the POSIX module's C<pause> function.
 
+=item sockatmark SOCKET
+
+Returns true if the socket is positioned at the out-of-band mark
+(also known as the urgent data mark), false otherwise.  Use right
+after reading from the socket.
+
+Not available directly, one has to import the function from
+the IO::Socket extension
+
+    use IO::Socket 'sockatmark';
+
+Even this doesn't guarantee that sockatmark() really is available,
+though, because sockatmark() is a relatively recent addition to
+the family of socket functions.  If it is unavailable, attempt to
+use it will fail
+
+	IO::Socket::atmark not implemented on this architecture ...
+
+See also L<IO::Socket>.
+
 =item socket SOCKET,DOMAIN,TYPE,PROTOCOL
 
 Opens a socket of the specified kind and attaches it to filehandle
diff --git a/pod/perlport.pod b/pod/perlport.pod
index 9f471388a6..e80f41ebd5 100644
--- a/pod/perlport.pod
+++ b/pod/perlport.pod
@@ -1665,6 +1665,11 @@ Not implemented. (S<Mac OS>, Plan9)
 
 Not implemented. (S<Mac OS>, Win32, VMS, S<RISC OS>, VOS)
 
+=item sockatmark SOCKET
+
+A relatively recent addition to socket functions, may not
+be implemented even in UNIX platforms.
+
 =item socketpair SOCKET1,SOCKET2,DOMAIN,TYPE,PROTOCOL
 
 Not implemented. (S<Mac OS>, Win32, VMS, S<RISC OS>, VOS, VM/ESA)
diff --git a/pod/perltoc.pod b/pod/perltoc.pod
index 386d6fd09e..b9d895f5fe 100644
--- a/pod/perltoc.pod
+++ b/pod/perltoc.pod
@@ -380,14 +380,14 @@ SOCKET,MSG,FLAGS,TO, send SOCKET,MSG,FLAGS, setpgrp PID,PGRP, setpriority
 WHICH,WHO,PRIORITY, setsockopt SOCKET,LEVEL,OPTNAME,OPTVAL, shift ARRAY,
 shift, shmctl ID,CMD,ARG, shmget KEY,SIZE,FLAGS, shmread ID,VAR,POS,SIZE,
 shmwrite ID,STRING,POS,SIZE, shutdown SOCKET,HOW, sin EXPR, sin, sleep
-EXPR, sleep, socket SOCKET,DOMAIN,TYPE,PROTOCOL, socketpair
-SOCKET1,SOCKET2,DOMAIN,TYPE,PROTOCOL, sort SUBNAME LIST, sort BLOCK LIST,
-sort LIST, splice ARRAY,OFFSET,LENGTH,LIST, splice ARRAY,OFFSET,LENGTH,
-splice ARRAY,OFFSET, splice ARRAY, split /PATTERN/,EXPR,LIMIT, split
-/PATTERN/,EXPR, split /PATTERN/, split, sprintf FORMAT, LIST, sqrt EXPR,
-sqrt, srand EXPR, srand, stat FILEHANDLE, stat EXPR, stat, study SCALAR,
-study, sub BLOCK, sub NAME, sub NAME BLOCK, substr
-EXPR,OFFSET,LENGTH,REPLACEMENT, substr EXPR,OFFSET,LENGTH, substr
+EXPR, sleep, sockatmark SOCKET, socket SOCKET,DOMAIN,TYPE,PROTOCOL,
+socketpair SOCKET1,SOCKET2,DOMAIN,TYPE,PROTOCOL, sort SUBNAME LIST, sort
+BLOCK LIST, sort LIST, splice ARRAY,OFFSET,LENGTH,LIST, splice
+ARRAY,OFFSET,LENGTH, splice ARRAY,OFFSET, splice ARRAY, split
+/PATTERN/,EXPR,LIMIT, split /PATTERN/,EXPR, split /PATTERN/, split, sprintf
+FORMAT, LIST, sqrt EXPR, sqrt, srand EXPR, srand, stat FILEHANDLE, stat
+EXPR, stat, study SCALAR, study, sub BLOCK, sub NAME, sub NAME BLOCK,
+substr EXPR,OFFSET,LENGTH,REPLACEMENT, substr EXPR,OFFSET,LENGTH, substr
 EXPR,OFFSET, symlink OLDFILE,NEWFILE, syscall LIST, sysopen
 FILEHANDLE,FILENAME,MODE, sysopen FILEHANDLE,FILENAME,MODE,PERMS, sysread
 FILEHANDLE,SCALAR,LENGTH,OFFSET, sysread FILEHANDLE,SCALAR,LENGTH, sysseek
@@ -1858,9 +1858,9 @@ select RBITS,WBITS,EBITS,TIMEOUT, semctl ID,SEMNUM,CMD,ARG, semget
 KEY,NSEMS,FLAGS, semop KEY,OPSTRING, setgrent, setpgrp PID,PGRP,
 setpriority WHICH,WHO,PRIORITY, setpwent, setsockopt
 SOCKET,LEVEL,OPTNAME,OPTVAL, shmctl ID,CMD,ARG, shmget KEY,SIZE,FLAGS,
-shmread ID,VAR,POS,SIZE, shmwrite ID,STRING,POS,SIZE, socketpair
-SOCKET1,SOCKET2,DOMAIN,TYPE,PROTOCOL, stat FILEHANDLE, stat EXPR, stat,
-symlink OLDFILE,NEWFILE, syscall LIST, sysopen
+shmread ID,VAR,POS,SIZE, shmwrite ID,STRING,POS,SIZE, sockatmark SOCKET,
+socketpair SOCKET1,SOCKET2,DOMAIN,TYPE,PROTOCOL, stat FILEHANDLE, stat
+EXPR, stat, symlink OLDFILE,NEWFILE, syscall LIST, sysopen
 FILEHANDLE,FILENAME,MODE,PERMS, system LIST, times, truncate
 FILEHANDLE,LENGTH, truncate EXPR,LENGTH, umask EXPR, umask, utime LIST,
 wait, waitpid PID,FLAGS