Adding upstream version 4.22.0.upstream/4.22.0

Signed-off-by: Daniel Baumann <daniel.baumann@progress-linux.org>

1 files changed, 617 insertions, 0 deletions

diff --git a/upstream/archlinux/man3/IO::Socket.3perl b/upstream/archlinux/man3/IO::Socket.3perl
new file mode 100644
index 00000000..70fb64d9
--- /dev/null
+++ b/upstream/archlinux/man3/IO::Socket.3perl
@@ -0,0 +1,617 @@
+.\" -*- mode: troff; coding: utf-8 -*-
+.\" Automatically generated by Pod::Man 5.01 (Pod::Simple 3.43)
+.\"
+.\" Standard preamble:
+.\" ========================================================================
+.de Sp \" Vertical space (when we can't use .PP)
+.if t .sp .5v
+.if n .sp
+..
+.de Vb \" Begin verbatim text
+.ft CW
+.nf
+.ne \\$1
+..
+.de Ve \" End verbatim text
+.ft R
+.fi
+..
+.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>.
+.ie n \{\
+.    ds C` ""
+.    ds C' ""
+'br\}
+.el\{\
+.    ds C`
+.    ds C'
+'br\}
+.\"
+.\" Escape single quotes in literal strings from groff's Unicode transform.
+.ie \n(.g .ds Aq \(aq
+.el       .ds Aq '
+.\"
+.\" If the F register is >0, we'll generate index entries on stderr for
+.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
+.\" entries marked with X<> in POD.  Of course, you'll have to process the
+.\" output yourself in some meaningful fashion.
+.\"
+.\" Avoid warning from groff about undefined register 'F'.
+.de IX
+..
+.nr rF 0
+.if \n(.g .if rF .nr rF 1
+.if (\n(rF:(\n(.g==0)) \{\
+.    if \nF \{\
+.        de IX
+.        tm Index:\\$1\t\\n%\t"\\$2"
+..
+.        if !\nF==2 \{\
+.            nr % 0
+.            nr F 2
+.        \}
+.    \}
+.\}
+.rr rF
+.\" ========================================================================
+.\"
+.IX Title "IO::Socket 3perl"
+.TH IO::Socket 3perl 2024-02-11 "perl v5.38.2" "Perl Programmers Reference Guide"
+.\" For nroff, turn off justification.  Always turn off hyphenation; it makes
+.\" way too many mistakes in technical documents.
+.if n .ad l
+.nh
+.SH NAME
+IO::Socket \- Object interface to socket communications
+.SH SYNOPSIS
+.IX Header "SYNOPSIS"
+.Vb 2
+\&    use strict;
+\&    use warnings;
+\&
+\&    use IO::Socket qw(AF_INET AF_UNIX);
+\&
+\&    # create a new AF_INET socket
+\&    my $sock = IO::Socket\->new(Domain => AF_INET);
+\&    # which is the same as
+\&    $sock = IO::Socket::INET\->new();
+\&
+\&    # create a new AF_UNIX socket
+\&    $sock = IO::Socket\->new(Domain => AF_UNIX);
+\&    # which is the same as
+\&    $sock = IO::Socket::UNIX\->new();
+.Ve
+.SH DESCRIPTION
+.IX Header "DESCRIPTION"
+\&\f(CW\*(C`IO::Socket\*(C'\fR provides an object-oriented, IO::Handle\-based interface to
+creating and using sockets via Socket, which provides a near one-to-one
+interface to the C socket library.
+.PP
+\&\f(CW\*(C`IO::Socket\*(C'\fR is a base class that really only defines methods for those
+operations which are common to all types of sockets. Operations which are
+specific to a particular socket domain have methods defined in subclasses of
+\&\f(CW\*(C`IO::Socket\*(C'\fR. See IO::Socket::INET, IO::Socket::UNIX, and
+IO::Socket::IP for examples of such a subclass.
+.PP
+\&\f(CW\*(C`IO::Socket\*(C'\fR will export all functions (and constants) defined by Socket.
+.SH "CONSTRUCTOR ARGUMENTS"
+.IX Header "CONSTRUCTOR ARGUMENTS"
+Given that \f(CW\*(C`IO::Socket\*(C'\fR doesn't have attributes in the traditional sense, the
+following arguments, rather than attributes, can be passed into the
+constructor.
+.PP
+Constructor arguments should be passed in \f(CW\*(C`Key => \*(AqValue\*(Aq\*(C'\fR pairs.
+.PP
+The only required argument is "Domain" in IO::Socket.
+.SS Blocking
+.IX Subsection "Blocking"
+.Vb 2
+\&    my $sock = IO::Socket\->new(..., Blocking => 1);
+\&    $sock = IO::Socket\->new(..., Blocking => 0);
+.Ve
+.PP
+If defined but false, the socket will be set to non-blocking mode. If not
+specified it defaults to \f(CW1\fR (blocking mode).
+.SS Domain
+.IX Subsection "Domain"
+.Vb 2
+\&    my $sock = IO::Socket\->new(Domain => IO::Socket::AF_INET);
+\&    $sock = IO::Socket\->new(Domain => IO::Socket::AF_UNIX);
+.Ve
+.PP
+The socket domain will define which subclass of \f(CW\*(C`IO::Socket\*(C'\fR to use. The two
+options available along with this distribution are \f(CW\*(C`AF_INET\*(C'\fR and \f(CW\*(C`AF_UNIX\*(C'\fR.
+.PP
+\&\f(CW\*(C`AF_INET\*(C'\fR is for the internet address family of sockets and is handled via
+IO::Socket::INET. \f(CW\*(C`AF_INET\*(C'\fR sockets are bound to an internet address and
+port.
+.PP
+\&\f(CW\*(C`AF_UNIX\*(C'\fR is for the unix domain socket and is handled via
+IO::Socket::UNIX. \f(CW\*(C`AF_UNIX\*(C'\fR sockets are bound to the file system as their
+address name space.
+.PP
+This argument is \fBrequired\fR. All other arguments are optional.
+.SS Listen
+.IX Subsection "Listen"
+.Vb 1
+\&    my $sock = IO::Socket\->new(..., Listen => 5);
+.Ve
+.PP
+Listen should be an integer value or left unset.
+.PP
+If provided, this argument will place the socket into listening mode. New
+connections can then be accepted using the "accept" in IO::Socket method. The
+value given is used as the \f(CWlisten(2)\fR queue size.
+.PP
+If the \f(CW\*(C`Listen\*(C'\fR argument is given, but false, the queue size will be set to
+5.
+.SS Timeout
+.IX Subsection "Timeout"
+.Vb 1
+\&    my $sock = IO::Socket\->new(..., Timeout => 5);
+.Ve
+.PP
+The timeout value, in seconds, for this socket connection. How exactly this
+value is utilized is defined in the socket domain subclasses that make use of
+the value.
+.SS Type
+.IX Subsection "Type"
+.Vb 1
+\&    my $sock = IO::Socket\->new(..., Type => IO::Socket::SOCK_STREAM);
+.Ve
+.PP
+The socket type that will be used. These are usually \f(CW\*(C`SOCK_STREAM\*(C'\fR,
+\&\f(CW\*(C`SOCK_DGRAM\*(C'\fR, or \f(CW\*(C`SOCK_RAW\*(C'\fR. If this argument is left undefined an attempt
+will be made to infer the type from the service name.
+.PP
+For example, you'll usually use \f(CW\*(C`SOCK_STREAM\*(C'\fR with a \f(CW\*(C`tcp\*(C'\fR connection and
+\&\f(CW\*(C`SOCK_DGRAM\*(C'\fR with a \f(CW\*(C`udp\*(C'\fR connection.
+.SH CONSTRUCTORS
+.IX Header "CONSTRUCTORS"
+\&\f(CW\*(C`IO::Socket\*(C'\fR extends the IO::Handle constructor.
+.SS new
+.IX Subsection "new"
+.Vb 1
+\&    my $sock = IO::Socket\->new();
+\&
+\&    # get a new IO::Socket::INET instance
+\&    $sock = IO::Socket\->new(Domain => IO::Socket::AF_INET);
+\&    # get a new IO::Socket::UNIX instance
+\&    $sock = IO::Socket\->new(Domain => IO::Socket::AF_UNIX);
+\&
+\&    # Domain is the only required argument
+\&    $sock = IO::Socket\->new(
+\&        Domain => IO::Socket::AF_INET, # AF_INET, AF_UNIX
+\&        Type => IO::Socket::SOCK_STREAM, # SOCK_STREAM, SOCK_DGRAM, ...
+\&        Proto => \*(Aqtcp\*(Aq, # \*(Aqtcp\*(Aq, \*(Aqudp\*(Aq, IPPROTO_TCP, IPPROTO_UDP
+\&        # and so on...
+\&    );
+.Ve
+.PP
+Creates an \f(CW\*(C`IO::Socket\*(C'\fR, which is a reference to a newly created symbol (see
+the Symbol package). \f(CW\*(C`new\*(C'\fR optionally takes arguments, these arguments
+are defined in "CONSTRUCTOR ARGUMENTS" in IO::Socket.
+.PP
+Any of the "CONSTRUCTOR ARGUMENTS" in IO::Socket may be passed to the
+constructor, but if any arguments are provided, then one of them must be
+the "Domain" in IO::Socket argument. The "Domain" in IO::Socket argument can,
+by default, be either \f(CW\*(C`AF_INET\*(C'\fR or \f(CW\*(C`AF_UNIX\*(C'\fR. Other domains can be used if a
+proper subclass for the domain family is registered. All other arguments will
+be passed to the \f(CW\*(C`configuration\*(C'\fR method of the package for that domain.
+.PP
+If the constructor fails it will return \f(CW\*(C`undef\*(C'\fR and set the \f(CW$errstr\fR package
+variable to contain an error message.
+.PP
+.Vb 2
+\&    $sock = IO::Socket\->new(...)
+\&        or die "Cannot create socket \- $IO::Socket::errstr\en";
+.Ve
+.PP
+For legacy reasons the error message is also set into the global \f(CW$@\fR
+variable, and you may still find older code which looks here instead.
+.PP
+.Vb 2
+\&    $sock = IO::Socket\->new(...)
+\&        or die "Cannot create socket \- $@\en";
+.Ve
+.SH METHODS
+.IX Header "METHODS"
+\&\f(CW\*(C`IO::Socket\*(C'\fR inherits all methods from IO::Handle and implements the
+following new ones.
+.SS accept
+.IX Subsection "accept"
+.Vb 2
+\&    my $client_sock = $sock\->accept();
+\&    my $inet_sock = $sock\->accept(\*(AqIO::Socket::INET\*(Aq);
+.Ve
+.PP
+The accept method will perform the system call \f(CW\*(C`accept\*(C'\fR on the socket and
+return a new object. The new object will be created in the same class as the
+listen socket, unless a specific package name is specified. This object can be
+used to communicate with the client that was trying to connect.
+.PP
+This differs slightly from the \f(CW\*(C`accept\*(C'\fR function in perlfunc.
+.PP
+In a scalar context the new socket is returned, or \f(CW\*(C`undef\*(C'\fR upon
+failure. In a list context a two-element array is returned containing
+the new socket and the peer address; the list will be empty upon failure.
+.SS atmark
+.IX Subsection "atmark"
+.Vb 4
+\&    my $integer = $sock\->atmark();
+\&    # read in some data on a given socket
+\&    my $data;
+\&    $sock\->read($data, 1024) until $sock\->atmark;
+\&
+\&    # or, export the function to use:
+\&    use IO::Socket \*(Aqsockatmark\*(Aq;
+\&    $sock\->read($data, 1024) until sockatmark($sock);
+.Ve
+.PP
+True if the socket is currently positioned at the urgent data mark, false
+otherwise. If your system doesn't yet implement \f(CW\*(C`sockatmark\*(C'\fR this will throw
+an exception.
+.PP
+If your system does not support \f(CW\*(C`sockatmark\*(C'\fR, the \f(CW\*(C`use\*(C'\fR declaration will
+fail at compile time.
+.SS autoflush
+.IX Subsection "autoflush"
+.Vb 6
+\&    # by default, autoflush will be turned on when referenced
+\&    $sock\->autoflush(); # turns on autoflush
+\&    # turn off autoflush
+\&    $sock\->autoflush(0);
+\&    # turn on autoflush
+\&    $sock\->autoflush(1);
+.Ve
+.PP
+This attribute isn't overridden from IO::Handle's implementation. However,
+since we turn it on by default, it's worth mentioning here.
+.SS bind
+.IX Subsection "bind"
+.Vb 5
+\&    use Socket qw(pack_sockaddr_in);
+\&    my $port = 3000;
+\&    my $ip_address = \*(Aq0.0.0.0\*(Aq;
+\&    my $packed_addr = pack_sockaddr_in($port, $ip_address);
+\&    $sock\->bind($packed_addr);
+.Ve
+.PP
+Binds a network address to a socket, just as \f(CWbind(2)\fR does. Returns true if
+it succeeded, false otherwise. You should provide a packed address of the
+appropriate type for the socket.
+.SS connected
+.IX Subsection "connected"
+.Vb 4
+\&    my $peer_addr = $sock\->connected();
+\&    if ($peer_addr) {
+\&        say "We\*(Aqre connected to $peer_addr";
+\&    }
+.Ve
+.PP
+If the socket is in a connected state, the peer address is returned. If the
+socket is not in a connected state, \f(CW\*(C`undef\*(C'\fR is returned.
+.PP
+Note that this method considers a half-open TCP socket to be "in a connected
+state".  Specifically, it does not distinguish between the
+\&\fBESTABLISHED\fR and \fBCLOSE-WAIT\fR TCP states; it returns the peer address,
+rather than \f(CW\*(C`undef\*(C'\fR, in either case.  Thus, in general, it cannot
+be used to reliably learn whether the peer has initiated a graceful shutdown
+because in most cases (see below) the local TCP state machine remains in
+\&\fBCLOSE-WAIT\fR until the local application calls "shutdown" in IO::Socket or
+\&\f(CW\*(C`close\*(C'\fR. Only at that point does this function return \f(CW\*(C`undef\*(C'\fR.
+.PP
+The "in most cases" hedge is because local TCP state machine behavior may
+depend on the peer's socket options. In particular, if the peer socket has
+\&\f(CW\*(C`SO_LINGER\*(C'\fR enabled with a zero timeout, then the peer's \f(CW\*(C`close\*(C'\fR will
+generate a \f(CW\*(C`RST\*(C'\fR segment. Upon receipt of that segment, the local TCP
+transitions immediately to \fBCLOSED\fR, and in that state, this method \fIwill\fR
+return \f(CW\*(C`undef\*(C'\fR.
+.SS getsockopt
+.IX Subsection "getsockopt"
+.Vb 3
+\&    my $value = $sock\->getsockopt(SOL_SOCKET, SO_REUSEADDR);
+\&    my $buf = $socket\->getsockopt(SOL_SOCKET, SO_RCVBUF);
+\&    say "Receive buffer is $buf bytes";
+.Ve
+.PP
+Get an option associated with the socket. Levels other than \f(CW\*(C`SOL_SOCKET\*(C'\fR
+may be specified here. As a convenience, this method will unpack a byte buffer
+of the correct size back into a number.
+.SS listen
+.IX Subsection "listen"
+.Vb 1
+\&    $sock\->listen(5);
+.Ve
+.PP
+Does the same thing that the \f(CWlisten(2)\fR system call does. Returns true if it
+succeeded, false otherwise. Listens to a socket with a given queue size.
+.SS peername
+.IX Subsection "peername"
+.Vb 1
+\&    my $sockaddr_in = $sock\->peername();
+.Ve
+.PP
+Returns the packed \f(CW\*(C`sockaddr\*(C'\fR address of the other end of the socket
+connection. It calls \f(CW\*(C`getpeername\*(C'\fR.
+.SS protocol
+.IX Subsection "protocol"
+.Vb 1
+\&    my $proto = $sock\->protocol();
+.Ve
+.PP
+Returns the number for the protocol being used on the socket, if
+known. If the protocol is unknown, as with an \f(CW\*(C`AF_UNIX\*(C'\fR socket, zero
+is returned.
+.SS recv
+.IX Subsection "recv"
+.Vb 5
+\&    my $buffer = "";
+\&    my $length = 1024;
+\&    my $flags = 0; # default. optional
+\&    $sock\->recv($buffer, $length);
+\&    $sock\->recv($buffer, $length, $flags);
+.Ve
+.PP
+Similar in functionality to "recv" in perlfunc.
+.PP
+Receives a message on a socket. Attempts to receive \f(CW$length\fR characters of
+data into \f(CW$buffer\fR from the specified socket. \f(CW$buffer\fR will be grown or
+shrunk to the length actually read. Takes the same flags as the system call of
+the same name. Returns the address of the sender if socket's protocol supports
+this; returns an empty string otherwise. If there's an error, returns
+\&\f(CW\*(C`undef\*(C'\fR. This call is actually implemented in terms of the \f(CWrecvfrom(2)\fR
+system call.
+.PP
+Flags are ORed together values, such as \f(CW\*(C`MSG_BCAST\*(C'\fR, \f(CW\*(C`MSG_OOB\*(C'\fR,
+\&\f(CW\*(C`MSG_TRUNC\*(C'\fR. The default value for the flags is \f(CW0\fR.
+.PP
+The cached value of "peername" in IO::Socket is updated with the result of
+\&\f(CW\*(C`recv\*(C'\fR.
+.PP
+\&\fBNote:\fR In Perl v5.30 and newer, if the socket has been marked as \f(CW\*(C`:utf8\*(C'\fR,
+\&\f(CW\*(C`recv\*(C'\fR will throw an exception. The \f(CW:encoding(...)\fR layer implicitly
+introduces the \f(CW\*(C`:utf8\*(C'\fR layer. See "binmode" in perlfunc.
+.PP
+\&\fBNote:\fR In Perl versions older than v5.30, depending on the status of the
+socket, either (8\-bit) bytes or characters are received. By default all
+sockets operate on bytes, but for example if the socket has been changed
+using "binmode" in perlfunc to operate with the \f(CW:encoding(UTF\-8)\fR I/O layer
+(see the "open" in perlfunc pragma), the I/O will operate on UTF8\-encoded
+Unicode characters, not bytes. Similarly for the \f(CW\*(C`:encoding\*(C'\fR layer: in
+that case pretty much any characters can be read.
+.SS send
+.IX Subsection "send"
+.Vb 6
+\&    my $message = "Hello, world!";
+\&    my $flags = 0; # defaults to zero
+\&    my $to = \*(Aq0.0.0.0\*(Aq; # optional destination
+\&    my $sent = $sock\->send($message);
+\&    $sent = $sock\->send($message, $flags);
+\&    $sent = $sock\->send($message, $flags, $to);
+.Ve
+.PP
+Similar in functionality to "send" in perlfunc.
+.PP
+Sends a message on a socket. Attempts to send the scalar message to the
+socket. Takes the same flags as the system call of the same name. On
+unconnected sockets, you must specify a destination to send to, in which case
+it does a \f(CWsendto(2)\fR syscall. Returns the number of characters sent, or
+\&\f(CW\*(C`undef\*(C'\fR on error. The \f(CWsendmsg(2)\fR syscall is currently unimplemented.
+.PP
+The \f(CW\*(C`flags\*(C'\fR option is optional and defaults to \f(CW0\fR.
+.PP
+After a successful send with \f(CW$to\fR, further calls to \f(CW\*(C`send\*(C'\fR on an
+unconnected socket without \f(CW$to\fR will send to the same address, and \f(CW$to\fR
+will be used as the result of "peername" in IO::Socket.
+.PP
+\&\fBNote:\fR In Perl v5.30 and newer, if the socket has been marked as \f(CW\*(C`:utf8\*(C'\fR,
+\&\f(CW\*(C`send\*(C'\fR will throw an exception. The \f(CW:encoding(...)\fR layer implicitly
+introduces the \f(CW\*(C`:utf8\*(C'\fR layer. See "binmode" in perlfunc.
+.PP
+\&\fBNote:\fR In Perl versions older than v5.30, depending on the status of the
+socket, either (8\-bit) bytes or characters are sent. By default all
+sockets operate on bytes, but for example if the socket has been changed
+using "binmode" in perlfunc to operate with the \f(CW:encoding(UTF\-8)\fR I/O layer
+(see the "open" in perlfunc pragma), the I/O will operate on UTF8\-encoded
+Unicode characters, not bytes. Similarly for the \f(CW\*(C`:encoding\*(C'\fR layer: in
+that case pretty much any characters can be sent.
+.SS setsockopt
+.IX Subsection "setsockopt"
+.Vb 2
+\&    $sock\->setsockopt(SOL_SOCKET, SO_REUSEADDR, 1);
+\&    $sock\->setsockopt(SOL_SOCKET, SO_RCVBUF, 64*1024);
+.Ve
+.PP
+Set option associated with the socket. Levels other than \f(CW\*(C`SOL_SOCKET\*(C'\fR
+may be specified here. As a convenience, this method will convert a number
+into a packed byte buffer.
+.SS shutdown
+.IX Subsection "shutdown"
+.Vb 3
+\&    $sock\->shutdown(SHUT_RD); # we stopped reading data
+\&    $sock\->shutdown(SHUT_WR); # we stopped writing data
+\&    $sock\->shutdown(SHUT_RDWR); # we stopped using this socket
+.Ve
+.PP
+Shuts down a socket connection in the manner indicated by the value passed in,
+which has the same interpretation as in the syscall of the same name.
+.PP
+This is useful with sockets when you want to tell the other side you're done
+writing but not done reading, or vice versa. It's also a more insistent form
+of \f(CW\*(C`close\*(C'\fR because it also disables the file descriptor in any
+forked copies in other processes.
+.PP
+Returns \f(CW1\fR for success; on error, returns \f(CW\*(C`undef\*(C'\fR if the socket is
+not a valid filehandle, or returns \f(CW0\fR and sets \f(CW$!\fR for any other failure.
+.SS sockdomain
+.IX Subsection "sockdomain"
+.Vb 1
+\&    my $domain = $sock\->sockdomain();
+.Ve
+.PP
+Returns the number for the socket domain type. For example, for
+an \f(CW\*(C`AF_INET\*(C'\fR socket the value of \f(CW&AF_INET\fR will be returned.
+.SS socket
+.IX Subsection "socket"
+.Vb 4
+\&    my $sock = IO::Socket\->new(); # no values given
+\&    # now let\*(Aqs actually get a socket with the socket method
+\&    # domain, type, and protocol are required
+\&    $sock = $sock\->socket(AF_INET, SOCK_STREAM, \*(Aqtcp\*(Aq);
+.Ve
+.PP
+Opens a socket of the specified kind and returns it. Domain, type, and
+protocol are specified the same as for the syscall of the same name.
+.SS socketpair
+.IX Subsection "socketpair"
+.Vb 3
+\&    my ($r, $w) = $sock\->socketpair(AF_UNIX, SOCK_STREAM, PF_UNSPEC);
+\&    ($r, $w) = IO::Socket::UNIX
+\&        \->socketpair(AF_UNIX, SOCK_STREAM, PF_UNSPEC);
+.Ve
+.PP
+Will return a list of two sockets created (read and write), or an empty list
+on failure.
+.PP
+Differs slightly from \f(CW\*(C`socketpair\*(C'\fR in perlfunc in that the argument list
+is a bit simpler.
+.SS sockname
+.IX Subsection "sockname"
+.Vb 1
+\&    my $packed_addr = $sock\->sockname();
+.Ve
+.PP
+Returns the packed \f(CW\*(C`sockaddr\*(C'\fR address of this end of the connection. It's the
+same as \f(CWgetsockname(2)\fR.
+.SS sockopt
+.IX Subsection "sockopt"
+.Vb 2
+\&    my $value = $sock\->sockopt(SO_REUSEADDR);
+\&    $sock\->sockopt(SO_REUSEADDR, 1);
+.Ve
+.PP
+Unified method to both set and get options in the \f(CW\*(C`SOL_SOCKET\*(C'\fR level. If
+called with one argument then "getsockopt" in IO::Socket is called, otherwise
+"setsockopt" in IO::Socket is called.
+.SS socktype
+.IX Subsection "socktype"
+.Vb 1
+\&    my $type = $sock\->socktype();
+.Ve
+.PP
+Returns the number for the socket type. For example, for
+a \f(CW\*(C`SOCK_STREAM\*(C'\fR socket the value of \f(CW&SOCK_STREAM\fR will be returned.
+.SS timeout
+.IX Subsection "timeout"
+.Vb 2
+\&    my $seconds = $sock\->timeout();
+\&    my $old_val = $sock\->timeout(5); # set new and return old value
+.Ve
+.PP
+Set or get the timeout value (in seconds) associated with this socket.
+If called without any arguments then the current setting is returned. If
+called with an argument the current setting is changed and the previous
+value returned.
+.PP
+This method is available to all \f(CW\*(C`IO::Socket\*(C'\fR implementations but may or may
+not be used by the individual domain subclasses.
+.SH EXAMPLES
+.IX Header "EXAMPLES"
+Let's create a TCP server on \f(CW\*(C`localhost:3333\*(C'\fR.
+.PP
+.Vb 3
+\&    use strict;
+\&    use warnings;
+\&    use feature \*(Aqsay\*(Aq;
+\&
+\&    use IO::Socket qw(AF_INET AF_UNIX SOCK_STREAM SHUT_WR);
+\&
+\&    my $server = IO::Socket\->new(
+\&        Domain => AF_INET,
+\&        Type => SOCK_STREAM,
+\&        Proto => \*(Aqtcp\*(Aq,
+\&        LocalHost => \*(Aq0.0.0.0\*(Aq,
+\&        LocalPort => 3333,
+\&        ReusePort => 1,
+\&        Listen => 5,
+\&    ) || die "Can\*(Aqt open socket: $IO::Socket::errstr";
+\&    say "Waiting on 3333";
+\&
+\&    while (1) {
+\&        # waiting for a new client connection
+\&        my $client = $server\->accept();
+\&
+\&        # get information about a newly connected client
+\&        my $client_address = $client\->peerhost();
+\&        my $client_port = $client\->peerport();
+\&        say "Connection from $client_address:$client_port";
+\&
+\&        # read up to 1024 characters from the connected client
+\&        my $data = "";
+\&        $client\->recv($data, 1024);
+\&        say "received data: $data";
+\&
+\&        # write response data to the connected client
+\&        $data = "ok";
+\&        $client\->send($data);
+\&
+\&        # notify client that response has been sent
+\&        $client\->shutdown(SHUT_WR);
+\&    }
+\&
+\&    $server\->close();
+.Ve
+.PP
+A client for such a server could be
+.PP
+.Vb 3
+\&    use strict;
+\&    use warnings;
+\&    use feature \*(Aqsay\*(Aq;
+\&
+\&    use IO::Socket qw(AF_INET AF_UNIX SOCK_STREAM SHUT_WR);
+\&
+\&    my $client = IO::Socket\->new(
+\&        Domain => AF_INET,
+\&        Type => SOCK_STREAM,
+\&        proto => \*(Aqtcp\*(Aq,
+\&        PeerPort => 3333,
+\&        PeerHost => \*(Aq0.0.0.0\*(Aq,
+\&    ) || die "Can\*(Aqt open socket: $IO::Socket::errstr";
+\&
+\&    say "Sending Hello World!";
+\&    my $size = $client\->send("Hello World!");
+\&    say "Sent data of length: $size";
+\&
+\&    $client\->shutdown(SHUT_WR);
+\&
+\&    my $buffer;
+\&    $client\->recv($buffer, 1024);
+\&    say "Got back $buffer";
+\&
+\&    $client\->close();
+.Ve
+.SH LIMITATIONS
+.IX Header "LIMITATIONS"
+On some systems, for an IO::Socket object created with \f(CW\*(C`new_from_fd\*(C'\fR,
+or created with "accept" in IO::Socket from such an object, the
+"protocol" in IO::Socket, "sockdomain" in IO::Socket and
+"socktype" in IO::Socket methods may return \f(CW\*(C`undef\*(C'\fR.
+.SH "SEE ALSO"
+.IX Header "SEE ALSO"
+Socket, IO::Handle, IO::Socket::INET, IO::Socket::UNIX,
+IO::Socket::IP
+.SH AUTHOR
+.IX Header "AUTHOR"
+Graham Barr.  \fBatmark()\fR by Lincoln Stein.  Currently maintained by the Perl 5
+Porters.  Please report all bugs at <https://github.com/Perl/perl5/issues>.
+.SH COPYRIGHT
+.IX Header "COPYRIGHT"
+Copyright (c) 1997\-8 Graham Barr <gbarr@pobox.com>. All rights reserved.
+This program is free software; you can redistribute it and/or
+modify it under the same terms as Perl itself.
+.PP
+The \fBatmark()\fR implementation: Copyright 2001, Lincoln Stein <lstein@cshl.org>.
+This module is distributed under the same terms as Perl itself.
+Feel free to use, modify and redistribute it as long as you retain
+the correct attribution.