/ 
net-ext-a8
/ Net::Inet

NAME

Net::Inet - Internet socket interface module

SYNOPSIS

use Net::Gen;		# optional
use Net::Inet;

DESCRIPTION

The Net::Inet module provides basic services for handling socket-based communications for the Internet protocol family. It inherits from Net::Gen, and is a base for Net::TCP and Net::UDP (future).

Public Methods

new

Usage:

$obj = new Net::Inet;
$obj = new Net::Inet $host, $service;
$obj = new Net::Inet \%parameters;
$obj = new Net::Inet $host, $service, \%parameters;

Returns a newly-initialised object of the given class. If called for a derived class, no validation of the supplied parameters will be performed. (This is so that the derived class can add the parameter validation it needs to the object before allowing the validation.) Otherwise, it will cause the parameters to be validated by calling its init method. In particular, this means that if both a host and a service are given, and a protocol and socket type are already known, then an object will only be returned if a connect() call was successful.

init

Usage:

return undef unless $self = $self->init;
return undef unless $self = $self->init(\%parameters);
return undef unless $self = $self->init($host, $service);
return undef unless $self = $self->init($host, $service, \%parameters);

Verifies that all previous parameter assignments are valid (via checkparams). Returns the incoming object on success, and undef on failure. Usually called only via a derived class's init method or its own new call.

bind

Usage:

$ok = $obj->bind;
$ok = $obj->bind($host, $service);

Sets up the srcaddrlist object parameter with the specified $host and $service arguments if supplied (via the thishost and thisport object parameters), and then returns the value from the inherited bind method.

Example:

$ok = $obj->bind(0, 'echo'); # attach to the TCP echo port
unbind

Usage:

$obj->unbind;

Deletes the thishost and thisport object parameters, and then (assuming that succeeds, which it should) returns the value from the inherited unbind method.

connect

Usage:

$ok = $obj->connect;
$ok = $obj->connect($host, $service);
$ok = $obj->connect([$host, $service]);

Attempts to establish a connection for the object. If the $host or $service arguments are specified, they will be used to set the desthost and destservice/destport object parameters, with side-effects of setting up the dstaddrlist object parameter. Then, the result of a call to the inherited connect method will be returned.

format_addr

Usage:

$string = $obj->format_addr($sockaddr);
$string = $obj->format_addr($sockaddr, $numeric_only);
$string = format_addr Module $sockaddr;
$string = format_addr Module $sockaddr, $numeric_only;

Returns a formatted representation of the address. This is a method so that it can be overridden by derived classes. It is used to implement ``pretty-printing'' methods for source and destination addresses. If the $numeric_only argument is true, the address and port number will be used even if they can be resolved to names. Otherwise, the resolved hostname and service name will be used if possible.

format_local_addr

Usage:

$string = $obj->format_local_addr;
$string = $obj->format_local_addr($numeric_only);

Returns a formatted representation of the local socket address associated with the object. A sugar-coated way of calling the format_addr method for the srcaddr object parameter.

format_remote_addr

Usage:

$string = $obj->format_remote_addr;

Returns a formatted representation of the remote socket address associated with the object. A sugar-coated way of calling the format_addr method for the dstaddr object parameter.

getsockinfo

An augmented form of Net::Gen::getsockinfo. Aside from updating more object parameters, it behaves the same as that in the base class. The additional object parameters which get set are lcladdr, lclhost, lclport, lclservice, remaddr, remhost, remport, and remservice. (They are described below.)

Protected Methods

[See the note in the Net::Gen documentation about my definition of protected methods in Perl.]

None.

Known Socket Options

These are the socket options known to the Net::Inet module itself:

IP_HDRINCL, IP_RECVDSTADDR, IP_RECVOPTS, IP_RECVRETOPTS, IP_TOS, IP_TTL, IP_ADD_MEMBERSHIP, IP_DROP_MEMBERSHIP, IP_MULTICAST_IF, IP_MULTICAST_LOOP, IP_MULTICAST_TTL, IP_OPTIONS, IP_RETOPTS

Known Object Parameters

These are the object parameters registered by the Net::Inet module itself:

IPproto

The name of the Internet protocol in use on the socket associated with the object. Set as a side-effect of setting the proto object parameter, and vice versa.

proto

Used the same way as with Net::Gen, but has a handler attached to keep it in sync with IPproto.

thishost

The source host name or address to use for the bind method. When used in conjunction with the thisservice or thisport object parameter, causes the srcaddrlist object parameter to be set, which is how it affects the bind() action. This parameter is validated, and must be either a valid internet address or a hostname for which an address can be found. If a hostname is given, and multiple addresses are found for it, then each address will be entered into the srcaddrlist array reference.

desthost

The destination host name or address to use for the connect method. When used in conjunction with the destservice or destport object parameter, causes the dstaddrlist object parameter to be set, which is how it affects the connect() action. This parameter is validated, and must be either a valid internet address or a hostname for which an address can be found. If a hostname is given, and multiple addresses are found for it, then each address will be entered into the dstaddrlist array reference, in order. This allows the connect method to attempt a connection to each address, as per RFC 1123.

thisservice

The source service name (or number) to use for the bind method. An attempt will be made to translate the supplied service name with getservbyname(). If that succeeds, or if it fails but the supplied value was strictly numeric, the port number will be set in the thisport object parameter. If the supplied value is not numeric and can't be translated, the attempt to set the value will fail. Otherwise, this causes the srcaddrlist object parameter to be updated, in preparation for an invocation of the bind method (possibly implicitly from the connect method).

thisport

The source service number (or name) to use for the bind method. An attempt will be made to translate the supplied service name with getservbyname() if it is not strictly numeric. If that succeeds, the given name will be set in the thisservice parameter, and the resolved port number will be set in the thisport object parameter. If the supplied value is strictly numeric, and a call to getservbyport can resolve a name for the service, the thisservice parameter will be updated appropriately. If the supplied value is not numeric and can't be translated, the attempt to set the value will fail. Otherwise, this causes the srcaddrlist object parameter to be updated, in preparation for an invocation of the bind method (possibly implicitly from the connect method).

destservice

The destination service name (or number) to use for the connect method. An attempt will be made to translate the supplied service name with getservbyname(). If that succeeds, or if it fails but the supplied value was strictly numeric, the port number will be set in the destport object parameter. If the supplied value is not numeric and can't be translated, the attempt to set the value will fail. Otherwise, if the desthost parameter has a defined value, this causes the dstaddrlist object parameter to be updated, in preparation for an invocation of the connect method.

destport

The destination service number (or name) to use for the connect method. An attempt will be made to translate the supplied service name with getservbyname() if it is not strictly numeric. If that succeeds, the given name will be set in the destservice parameter, and the resolved port number will be set in the destport parameter. If the supplied value is strictly numeric, and a call to getservbyport can resolve a name for the service, the destservice parameter will be updated appropriately. If the supplied value is not numeric and can't be translated, the attempt to set the value will fail. Otherwise, if the desthost parameter has a defined value, this causes the dstaddrlist object parameter to be updated, in preparation for an invocation of the connect method.

lcladdr

The local IP address stashed by the getsockinfo method after a successful connect() call.

lclhost

The local hostname stashed by the getsockinfo method after a successful connect(), as resolved from the lcladdr object parameter.

lclport

The local port number stashed by the getsockinfo method after a successful connect() call.

lclservice

The local service name stashed by the getsockinfo method after a successful connect(), as resolved from the lclport object parameter.

remaddr

The remote IP address stashed by the getsockinfo method after a successful connect() call.

remhost

The remote hostname stashed by the getsockinfo method after a successful connect(), as resolved from the remaddr object parameter.

remport

The remote port number stashed by the getsockinfo method after a successful connect() call.

remservice

The remote service name stashed by the getsockinfo method after a successful connect(), as resolved from the remport object parameter.

Non-Method Subroutines

inet_aton

Usage:

$in_addr = inet_aton('192.0.2.1');

Returns the packed AF_INET address in network order, if it is validly formed, or undef on error.

inet_addr

A synonym for inet_aton() (for old fogeys like me who forget about the new name). (Yes, I know it's different in C, but in Perl there's no need to propagate the old inet_addr() braindamage, so I didn't.)

inet_ntoa

Usage:

$addr_string = inet_ntoa($in_addr);

Returns the ASCII representation of the AF_INET address provided (if possible), or undef on error.

htonl/htons/ntohl/ntohs

As you'd expect, I think.

pack_sockaddr_in

Usage:

$connect_address = pack_sockaddr_in($family, $port, $in_addr);

Returns the packed struct sockaddr_in corresponding to the provided $family, $port, and $in_addr arguments. The $family and $port arguments must be numbers, and the $in_addr argument must be a packed struct in_addr such as the trailing elements from perl's gethostent() return list.

unpack_sockaddr_in

Usage:

($family, $port, $in_addr) = unpack_sockaddr_in($connected_address);

Returns the address family, port, and packed struct in_addr from the supplied packed struct sockaddr_in. This is the inverse of pack_sockaddr_in().

Exports

default

INADDR_ALLHOSTS_GROUP, INADDR_ANY, INADDR_BROADCAST, INADDR_LOOPBACK, INADDR_MAX_LOCAL_GROUP, INADDR_NONE, INADDR_UNSPEC_GROUP, IPPORT_RESERVED, IPPORT_USERRESERVED, IPPROTO_EGP, IPPROTO_EON, IPPROTO_GGP, IPPROTO_HELLO, IPPROTO_ICMP, IPPROTO_IDP, IPPROTO_IGMP, IPPROTO_IP, IPPROTO_MAX, IPPROTO_PUP, IPPROTO_RAW, IPPROTO_TCP, IPPROTO_TP, IPPROTO_UDP, htonl, htons, inet_addr, inet_aton, inet_ntoa, ntohl, ntohs

exportable

ICMP_ADVLENMIN, ICMP_ECHO, ICMP_ECHOREPLY, ICMP_IREQ, ICMP_IREQREPLY, ICMP_MASKLEN, ICMP_MASKREPLY, ICMP_MASKREQ, ICMP_MAXTYPE, ICMP_MINLEN, ICMP_PARAMPROB, ICMP_REDIRECT, ICMP_REDIRECT_HOST, ICMP_REDIRECT_NET, ICMP_REDIRECT_TOSHOST, ICMP_REDIRECT_TOSNET, ICMP_SOURCEQUENCH, ICMP_TIMXCEED, ICMP_TIMXCEED_INTRANS, ICMP_TIMXCEED_REASS, ICMP_TSLEN, ICMP_TSTAMP, ICMP_TSTAMPREPLY, ICMP_UNREACH, ICMP_UNREACH_HOST, ICMP_UNREACH_NEEDFRAG, ICMP_UNREACH_NET, ICMP_UNREACH_PORT, ICMP_UNREACH_PROTOCOL, ICMP_UNREACH_SRCFAIL, IN_CLASSA_HOST, IN_CLASSA_MAX, IN_CLASSA_NET, IN_CLASSA_NSHIFT, IN_CLASSA_SUBHOST, IN_CLASSA_SUBNET, IN_CLASSA_SUBNSHIFT, IN_CLASSB_HOST, IN_CLASSB_MAX, IN_CLASSB_NET, IN_CLASSB_NSHIFT, IN_CLASSB_SUBHOST, IN_CLASSB_SUBNET, IN_CLASSB_SUBNSHIFT, IN_CLASSC_HOST, IN_CLASSC_MAX, IN_CLASSC_NET, IN_CLASSC_NSHIFT, IN_CLASSD_HOST, IN_CLASSD_NET, IN_CLASSD_NSHIFT, IN_LOOPBACKNET, IPFRAGTTL, IPOPT_CONTROL, IPOPT_DEBMEAS, IPOPT_EOL, IPOPT_LSRR, IPOPT_MINOFF, IPOPT_NOP, IPOPT_OFFSET, IPOPT_OLEN, IPOPT_OPTVAL, IPOPT_RESERVED1, IPOPT_RESERVED2, IPOPT_RR, IPOPT_SATID, IPOPT_SECURITY, IPOPT_SECUR_CONFID, IPOPT_SECUR_EFTO, IPOPT_SECUR_MMMM, IPOPT_SECUR_RESTR, IPOPT_SECUR_SECRET, IPOPT_SECUR_TOPSECRET, IPOPT_SECUR_UNCLASS, IPOPT_SSRR, IPOPT_TS, IPOPT_TS_PRESPEC, IPOPT_TS_TSANDADDR, IPOPT_TS_TSONLY, IPPORT_TIMESERVER, IPTOS_LOWDELAY, IPTOS_PREC_CRITIC_ECP, IPTOS_PREC_FLASH, IPTOS_PREC_FLASHOVERRIDE, IPTOS_PREC_IMMEDIATE, IPTOS_PREC_INTERNETCONTROL, IPTOS_PREC_NETCONTROL, IPTOS_PREC_PRIORITY, IPTOS_PREC_ROUTINE, IPTOS_RELIABILITY, IPTOS_THROUGHPUT, IPTTLDEC, IPVERSION, IP_ADD_MEMBERSHIP, IP_DEFAULT_MULTICAST_LOOP, IP_DEFAULT_MULTICAST_TTL, IP_DF, IP_DROP_MEMBERSHIP, IP_HDRINCL, IP_MAXPACKET, IP_MAX_MEMBERSHIPS, IP_MF, IP_MSS, IP_MULTICAST_IF, IP_MULTICAST_LOOP, IP_MULTICAST_TTL, IP_OPTIONS, IP_RECVDSTADDR, IP_RECVOPTS, IP_RECVRETOPTS, IP_RETOPTS, IP_TOS, IP_TTL, MAXTTL, SUBNETSHIFT, pack_sockaddr_in, unpack_sockaddr_in

tags

None, yet. Taking suggestions for useful groupings.

NYI

This is still missing a way to pretty-print the connection information after a successful connect() or accept(). [Not still true, but the following yet holds.] This is largely because I'm not satisfied with any of the obvious ways to do it. Now taking suggestions. Proposals so far:

    ($peerproto, $peername, $peeraddr, $peerport, $peerservice) =
	$obj->getsockinfo;
    @conninfo = $obj->getsockinfo($sockaddr_in);
    # the above pair are a single proposal

    %conninfo = $obj->getsockinfo;
    %conninfo = $obj->getsockinfo($sockaddr_in);
    # for these, the keys would be qw(proto hostname address port service)

Of course, it's probably better to return references rather than actual arrays, but you get the idea.

AUTHOR

Spider Boardman <spider@Orb.Nashua.NH.US>