NAME

  LaBrea::Tarpit::NetIO

SYNOPSIS

  use LaBrea::Tarpit::NetIO qw (
        TARPIT_PORT
        open_listen_sock
        open_tcp
        alarm_wrap
        daemon_handler
        read_daemon
        fetch
        reap_kids
        set_so_linger
    [plus any Socket.pm variable]
  );

  $error=open_listen_sock(HANDLE,address,port);
  $error=open_tcp(*S,$host,$port);
  *rv = alarm_wrap($timeout,$subref,@args);
  $subref=daemon_handler(*HANDLE,$target);
  read_daemon($subref,\@response);
  $err=fetch($target,\@response,$command);
  $alive = reap_kids(\%kids);
  $rv = set_so_linger(*HANDLE,$seconds);

DESCRIPTION

NetIO contains TCP client and server modules used by Tarpit modules.

NetIO has available for EXPORT, any variable from the standard Socket.pm module.

$error=open_listen_sock(HANDLE,address,port);

Opens a server listening socket on HANDLE

  input:        HANDLE,
                address,  name or ip
                        defaults to all 
                        interfaces if false 
                port      defaults to 8686

  returns:      false on success
                or error message

$error=open_tcp(*S,$host,$port);

Open a tcp connection on port to host.

  input:        *S,hostname, port
  returns:      false on success
                error message on failure

$rv = alarm_wrap($timeout,$subref,@args);

Provides an alarm wrapper for subroutines that may time out or die.

  input:        timeout,
                $subref,
                arguments for $subref

  returns:      $subref return value(s)
                  on error
                undef or () on error
        $@ is set with error value
        which will contain the string
        'alarm_wrap timeout' if
        the fault was timeout only

        timeout is ignored if false

$subref=daemon_handler(*HANDLE,$target);

Opens a handle *HANDLE pointing to the Tarpit daemon, pipe or file and returns a CODEREF to a subroutine that will read full lines of data from the HANDLE. Do not try to read the handle directly.

  input:   *HANDLE
           file name/path
            or
           hash ->{d_host} [optional]
                ->{d_port} [optional]

If target is a HASH and d_host and/or d_port are not specified, they default to localhost:8686

  returns: subref or undef on open fail

  usage:  $present = daemon_handler(*H,$t);
          while ( $data = &$present ) {
            do something with $data;
          }
          close H;

read_daemon($subref,\@response);

read_daemon retrieves the response text from a file or daemon and places the lines in array.

  input:        $subref to execute
                pointer to @response

  returns:      number of lines
                fills @response

  Note: use 'alarm_wrap' with this routine

$error=fetch($target,\@response,$command);

fetch a response from target using args. Essentially a combination of daemon_handler and read_daemon wrapped with alarm_wrap. Retrieves data from the host or file specified by target. The args argument is ignored if target is a file.

  input:  target, # hash->{host} [optional]
                  # hash->{port} [optional]
                  # hash->{d_timeout} [optional]
          \@response,   # result lines
          command,              # what to tell host

  returns:      error if fail
                false on success

$alive = reap_kids(\%kids);

Non-blocking reaper for PID's in (keys %kids). Deletes zombie children from %kids and returns the number of kids remaining.

  input:        \%kids  # hash of child PID's
  returns:      number of kids remaining

$rv = set_so_linger(*HANDLE,$seconds);

  Set SO_LINGER on top level socket

  input:        *HANDLE, seconds
  returns:      true = success, false = fail

EXPORT_OK

        TARPIT_PORT
        open_listen_sock
        open_tcp
        alarm_wrap
        daemon_handler
        read_daemon
        fetch
        reap_kids
        set_so_linger
    [plus any Socket.pm variable]

COPYRIGHT

Copyright 2002, Michael Robinton & BizSystems This program is free software; you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation; either version 2 of the License, or (at your option) any later version.

This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details.

You should have received a copy of the GNU General Public License along with this program; if not, write to the Free Software Foundation, Inc., 59 Temple Place - Suite 330, Boston, MA 02111-1307, USA.

AUTHOR

Michael Robinton, michael@bizsystems.com

SEE ALSO

perl(1), Socket(3), LaBrea::Tarpit(3), LaBrea::Tarpit::Get(3), LaBrea::Tarpit::Report(3), LaBrea::Tarpit::Util(3), LaBrea::Tarpit::DShield(3), LaBrea::Tarpit::Codes(3)