


lib::IO::Socket(3Perl Programmers Reference Gulib::IO::Socket(3p)


NAME
       IO::Socket - Object interface to socket communications

SYNOPSIS
           use IO::Socket;


DESCRIPTION
       IO::Socket provides an object interface to creating and
       using sockets. It is built upon the the IO::Handle manpage
       interface and inherits all the methods defined by the
       IO::Handle manpage.

       IO::Socket only defines methods for those operations which
       are common to all types of socket. Operations which are
       specified to a socket in a particular domain have methods
       defined in sub classes of IO::Socket

       IO::Socket will export all functions (and constants)
       defined by the Socket manpage.

CONSTRUCTOR
       new ( [ARGS] )
           Creates an IO::Socket, which is a reference to a newly
           created symbol (see the Symbol package). new
           optionally takes arguments, these arguments are in
           key-value pairs.  new only looks for one key Domain
           which tells new which domain the socket will be in.
           All other arguments will be passed to the
           configuration method of the package for that domain,
           See below.

           IO::Sockets will be in autoflush mode after creation.
           Note that versions of IO::Socket prior to 1.1603 (as
           shipped with Perl 5.004_04) did not do this.   So if
           you need backward compatibility, you should set
           autoflush explicitly.

METHODS
       See the perlfunc manpage for complete descriptions of each
       of the following supported IO::Socket methods, which are
       just front ends for the corresponding built-in functions:

           socket
           socketpair
           bind
           listen
           accept
           send
           recv
           peername (getpeername)
           sockname (getsockname)

       Some methods take slightly different arguments to those



29/Apr/1999            perl 5.005, patch 03                     1





lib::IO::Socket(3Perl Programmers Reference Gulib::IO::Socket(3p)


       defined in the perlfunc manpage in attempt to make the
       interface more flexible. These are

       accept([PKG])
           perform the system call accept on the socket and
           return a new object. The new object will be created in
           the same class as the listen socket, unless PKG is
           specified. This object can be used to communicate with
           the client that was trying to connect. In a scalar
           context the new socket is returned, or undef upon
           failure. In an array context a two-element array is
           returned containing the new socket and the peer
           address, the list will be empty upon failure.

           Additional methods that are provided are

       timeout([VAL])
           Set or get the timeout value 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.

       sockopt(OPT [, VAL])
           Unified method to both set and get options in the
           SOL_SOCKET level. If called with one argument then
           getsockopt is called, otherwise setsockopt is called.

       sockdomain
           Returns the numerical number for the socket domain
           type. For example, for a AF_INET socket the value of
           &AF_INET will be returned.

       socktype
           Returns the numerical number for the socket type. For
           example, for a SOCK_STREAM socket the value of
           &SOCK_STREAM will be returned.

       protocol
           Returns the numerical number for the protocol being
           used on the socket, if known. If the protocol is
           unknown, as with an AF_UNIX socket, zero is returned.

SUB-CLASSES
       IO::Socket::INET

       IO::Socket::INET provides a constructor to create an
       AF_INET domain socket and some related methods. The
       constructor can take the following options








29/Apr/1999            perl 5.005, patch 03                     2





lib::IO::Socket(3Perl Programmers Reference Gulib::IO::Socket(3p)


           PeerAddr    Remote host address          <hostname>[:<port>]
           PeerPort    Remote port or service       <service>[(<no>)] | <no>
           LocalAddr   Local host bind address      hostname[:port]
           LocalPort   Local host bind port         <service>[(<no>)] | <no>
           Proto       Protocol name (or number)    "tcp" | "udp" | ...
           Type        Socket type                  SOCK_STREAM | SOCK_DGRAM | ...
           Listen      Queue size for listen
           Reuse       Set SO_REUSEADDR before binding
           Timeout     Timeout value for various operations

       If Listen is defined then a listen socket is created, else
       if the socket type, which is derived from the protocol, is
       SOCK_STREAM then connect() is called.

       The PeerAddr can be a hostname or the IP-address on the
       "xx.xx.xx.xx" form.  The PeerPort can be a number or a
       symbolic service name.  The service name might be followed
       by a number in parenthesis which is used if the service is
       not known by the system.  The PeerPort specification can
       also be embedded in the PeerAddr by preceding it with a
       ":".

       If Proto is not given and you specify a symbolic PeerPort
       port, then the constructor will try to derive Proto from
       the service name.  As a last resort Proto "tcp" is
       assumed.  The Type parameter will be deduced from Proto if
       not specified.

       If the constructor is only passed a single argument, it is
       assumed to be a PeerAddr specification.

       Examples:

          $sock = IO::Socket::INET->new(PeerAddr => 'www.perl.org',
                                        PeerPort => 'http(80)',
                                        Proto    => 'tcp');

          $sock = IO::Socket::INET->new(PeerAddr => 'localhost:smtp(25)');

          $sock = IO::Socket::INET->new(Listen    => 5,
                                        LocalAddr => 'localhost',
                                        LocalPort => 9000,
                                        Proto     => 'tcp');

          $sock = IO::Socket::INET->new('127.0.0.1:25');


       METHODS


       sockaddr ()
           Return the address part of the sockaddr structure for
           the socket




29/Apr/1999            perl 5.005, patch 03                     3





lib::IO::Socket(3Perl Programmers Reference Gulib::IO::Socket(3p)


       sockport ()
           Return the port number that the socket is using on the
           local host

       sockhost ()
           Return the address part of the sockaddr structure for
           the socket in a text form xx.xx.xx.xx

       peeraddr ()
           Return the address part of the sockaddr structure for
           the socket on the peer host

       peerport ()
           Return the port number for the socket on the peer
           host.

       peerhost ()
           Return the address part of the sockaddr structure for
           the socket on the peer host in a text form xx.xx.xx.xx

       IO::Socket::UNIX

       IO::Socket::UNIX provides a constructor to create an
       AF_UNIX domain socket and some related methods. The
       constructor can take the following options

           Type        Type of socket (eg SOCK_STREAM or SOCK_DGRAM)
           Local       Path to local fifo
           Peer        Path to peer fifo
           Listen      Create a listen socket


       METHODS


       hostpath()
           Returns the pathname to the fifo at the local end

       peerpath()
           Returns the pathname to the fifo at the peer end

SEE ALSO
       the Socket manpage, the IO::Handle manpage

AUTHOR
       Graham Barr <Graham.Barr@tiuk.ti.com>

COPYRIGHT
       Copyright (c) 1996 Graham Barr. All rights reserved. This
       program is free software; you can redistribute it and/or
       modify it under the same terms as Perl itself.






29/Apr/1999            perl 5.005, patch 03                     4





lib::IO::Socket(3Perl Programmers Reference Gulib::IO::Socket(3p)



























































29/Apr/1999            perl 5.005, patch 03                     5


