GT::Socket::Client - Socket module designed for TCP clients
use GT::Socket::Client qw/:crlf/;
my $socket = GT::Socket::Client->open(
host => "gossamer-threads.com",
port => "shell", # AKA port 514
timeout => 10
) or die GT::Socket::Client->error;
# $socket is now a socket connected to the host. Use
# it as you would use any socket.
$sock->readline(my $line);
print "Read this line from the socket: $line";
print $sock "That line" . CRLF;
$sock->readblock(my $block, 4096);
print "Read 4KB from the socket: $block";
print $sock "QUIT" . CRLF;
$sock->readall(my $all);
print "Everything else from the socket: $all";
print $sock "Something else" . CRLF;
This module is a basic socket module that is designed to only handle basic socket connection and simple read capabilities. Anything else that you want to do with the socket is entirely up to you - this doesn't try to support superfluous options that only a few connections will ever use, or options that should be done in the code using this module instead of the module itself. See the GT::WWW::http and GT::WWW::https modules for a good working example.
By default, GT::Socket::Client exports nothing, however it can export the LF, CR, CRLF, $LF, $CR, and $CRLF constants, individually, or together via the ':crlf' export tag.
Takes a hash (not hash reference) of socket options, as follows:
alarm() function; on other systems
(such as Windows), this argument has no effect.
error() method, which will always be set to the error message when
a problem occurs. Provide a true value if you want the warn()s to appear.
This method reads a single line from the socket. It takes one argument, which
must be a scalar which will be set to the line read. See the eol() method,
which allows you to specify an EOL character other than ``\012''. Note that on a
blocking socket, this will block until it can read a full line (or the server
closes the connection). On a non-blocking socket, the amount of time it will
wait for input is dependent on the value of the read_wait() method.
1 is returned on success, undef on failure.
This method attempts to read a certain number of bytes from the server. This
takes two arguments: like readline(), the first argument is a scalar that will
be set to the data read. The second argument is the amount of data that may be
read. Note that on a blocking socket, this will block until the required
amount of data is read, or the socket is closed. On a non-blocking socket, this
will return once the requested amount of data is read, the socket closes, or
there is no input for read_wait seconds (See read_wait).
Note that a block size of -1 makes the socket read until the connection is
closed, in the case of blocking sockets, or until the read_wait() is hit.
The number of bytes read is returned on success, undef on failure.
A synonym for $obj->readblock($_[0], -1) - in other words, it reads all
available data (waiting for up to read_wait seconds, if non-blocking).
A useful function for non-blocking sockets (completely useless for blocking sockets, on which it simply becomes a readall call). Basically, this works like readall(), above, but it will terminate immediately if it encounters a pattern that you provide on the end of the data read. Note that this does NOT work as a delimiter, but is useful for protocols such as POP3 when you want to read as much as you can, but know what should be at the end of what you read. The sole advantage of this is that it allows you to avoid the read_wait timeout that would otherwise be required at the end of a data stream.
It takes two arguments - the first is a string or array reference of strings
containing the trailing string data. The second is a scalar that will be set
to the data read. For example, for POP3 you might use: "\n.\r\n". You can
optionally pass in a third argument, which is used during the first read - if
the result of the first read is equal to the string passed in, it's returned.
Using the POP3 example again, this might be ".\r\n" - to handle an empty
response.
[Non-blocking sockets only] This adjusts the number of seconds passed to
select() to poll the socket for available data. The default value is 0.05,
which should work in most situations.
[Non-blocking sockets only] This method is used to set the wait time for reads. On a local or very fast connection, this can be set to a low value (i.e. 0.1 seconds), but on a typical slower internet connection, longer wait times for reading are usually necessary. Hence, the default is a wait time of 5 seconds. In effect, an attempt to read all data will end after nothing has been received for this many seconds.
Sends data to the server. Takes the data to send. This does The Right Thing for either non-blocking or blocking sockets.
This method takes one or more character, and uses it for the EOL character(s)
used by readline. If called without any argument, the EOL character for the
current object is returned.
If an error (such as connection, socket, etc.) occurs, you can access it via
the error() method. This can be called as either a class or instance method,
since open() return undef instead of an object if the connection fails.
Once a connection has been established, you can call this method to get the iaddr value for the connection. This value is as returned by Socket.pm's inet_aton function.
Once a connection has been established, this method can be used to determine
the port connected to. Note that this is not necessarily the same as the value
of the port option passed to open() - the return value of this function will
always be numeric (e.g. 25), even if a service name (e.g. "smtp") was
passed to open().
the GT::Socket manpage - A socket module made for Links SQL.
Jason Rhinelander
Copyright (c) 2004 Gossamer Threads Inc. All Rights Reserved. http://www.gossamer-threads.com/
Revision: $Id: Client.pm,v 1.15 2004/02/17 01:33:07 jagerman Exp $