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)