/ 
Net-ext-0.74
River stage one • 2 direct dependents • 2 total dependents
/ 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.

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(7)'); # attach to the local 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. This used to be a separate implementation in this package, but is now inherited from the Socket module.

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. This used to be a separate implementation in this package, but is now inherited from the Socket module.

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. This differs from the implementation in the Socket module in that the $family argument is present and used.

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(). This differs from the implementation in the Socket module in that the $family value from the socket address is returned.

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
sockopts	=> [qw(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)]
routines	=> [qw(pack_sockaddr_in unpack_sockaddr_in
		       inet_ntoa inet_aton inet_addr
		       htonl ntohl htons ntohs)]
icmpvalues	=> [qw(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)]
ipoptions	=> [qw(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)]
iptosvalues	=> [qw(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)]
protocolvalues	=> [qw(INADDR_ALLHOSTS_GROUP INADDR_ANY
		       INADDR_BROADCAST INADDR_LOOPBACK
		       INADDR_MAX_LOCAL_GROUP INADDR_NONE
		       INADDR_UNSPEC_GROUP
		       IP_DF IP_MAXPACKET IP_MF IP_MSS
		       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
		       IPFRAGTTL
		       IPTTLDEC IPVERSION)]
ipmulticast	=> [qw(IP_ADD_MEMBERSHIP IP_DEFAULT_MULTICAST_LOOP
		       IP_DEFAULT_MULTICAST_TTL IP_DROP_MEMBERSHIP
		       IP_MAX_MEMBERSHIPS IP_MULTICAST_IF
		       IP_MULTICAST_LOOP IP_MULTICAST_TTL)]

NOTES

Anywhere a service or port argument is used above, the allowed syntax is either a service name, a port number, or a service name with a caller-supplied default port number. Examples are 'echo', 7, and 'echo(7)', respectively. For a service argument, a bare port number must be translatable into a service name with getservbyport() or an error will result. A service name must be translatable into a port with getservbyname() or an error will result. However, a service name with a default port number will succeed (by using the supplied default) even if the translation with getservbyname() fails.

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>