lib::Net::Inet(User Contributed Perl Documentatilib::Net::Inet(3)NAMENet::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 set up the parameter
validation it needs in 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, then an object will only be
returned if a connect() call was successful.
init Usage:
return undef unless $self->init;
return undef unless $self->init(\%parameters);
return undef unless $self->init($host, $service);
return undef unless $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);
$ok = $obj->bind($host, $service, \%parameters);
24/Aug/1997 perl 5.005, patch 03 1
lib::Net::Inet(User Contributed Perl Documentatilib::Net::Inet(3)
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. Changing of parameters is also allowed,
mainly for setting debug status or timeouts.
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, \%parameters);
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. Changing
of parameters is also allowed, mainly for setting
debug status or timeouts.
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.
24/Aug/1997 perl 5.005, patch 03 2
lib::Net::Inet(User Contributed Perl Documentatilib::Net::Inet(3)
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 in the section on
/"Known Object Parameters below.)
Protected Methods
[See the note in the section on Protected Methods in the
Net::Gen manpage 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:
24/Aug/1997 perl 5.005, patch 03 3
lib::Net::Inet(User Contributed Perl Documentatilib::Net::Inet(3)
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
24/Aug/1997 perl 5.005, patch 03 4
lib::Net::Inet(User Contributed Perl Documentatilib::Net::Inet(3)
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 bind() or connect() call.
lclhost
The local hostname stashed by the getsockinfo method
after a successful bind() or connect(), as resolved
from the lcladdr object parameter.
24/Aug/1997 perl 5.005, patch 03 5
lib::Net::Inet(User Contributed Perl Documentatilib::Net::Inet(3)
lclport
The local port number stashed by the getsockinfo
method after a successful bind() or connect() call.
lclservice
The local service name stashed by the getsockinfo
method after a successful bind() or connect(), as
resolved from the lclport object parameter.
remaddr
The remote IP address stashed by the getsockinfo
method after a successful bind() or connect() call.
remhost
The remote hostname stashed by the getsockinfo method
after a successful bind() or connect(), as resolved
from the remaddr object parameter.
remport
The remote port number stashed by the getsockinfo
method after a successful bind() or connect() call.
remservice
The remote service name stashed by the getsockinfo
method after a successful bind() or 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.
24/Aug/1997 perl 5.005, patch 03 6
lib::Net::Inet(User Contributed Perl Documentatilib::Net::Inet(3)
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);
$connect_address = pack_sockaddr_in($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 available (though optional).
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.
INADDR_UNSPEC_GROUP
INADDR_ALLHOSTS_GROUP
INADDR_ALLRTRS_GROUP
INADDR_MAX_LOCAL_GROUP
Constant routines returning the unspecified local,
all hosts, all routers, or the maximum possible local
IP multicast group address, respectively. These
routines return results in the form of a packed
struct inaddr much like INADDR_ANY results described
in the INADDR_ANY entry in the Socket manpage.
24/Aug/1997 perl 5.005, patch 03 7
lib::Net::Inet(User Contributed Perl Documentatilib::Net::Inet(3)
IN_CLASSA
IN_CLASSB
IN_CLASSC
IN_CLASSD
IN_MULTICAST
IN_EXPERIMENTAL
IN_BADCLASS
Usage:
$boolean = IN_EXPERIMENTAL(INADDR_ALLHOSTS_GROUP);
$boolean = IN_CLASSA(0x7f000001);
These routines return the network class information
for the supplied IP address. Of these, only
IN_BADCLASS() and IN_MULTICAST() are really useful in
today's Internet, since the advent of CIDR (classless
Internet domain routing). In particular,
IN_EXPERIMENTAL() is at the mercy of your vendor's
definition. The first example above will be true
only on older systems, which almost certainly don't
support IP multicast anyway. The argument to any of
these functions can be either a packed struct inaddr
such as that returned by inet_ntoa() or
unpack_sockaddr_in(), or an integer (or integer
expression) giving an IP address in host byte order.
IPOPT_CLASS
IPOPT_COPIED
IPOPT_NUMBER
Usage:
$optnum = IPOPT_NUMBER($option);
These routines extract information from IP option
numbers, as per the information on IP options in RFC
791.
... Other constants which relate to parts of IP or ICMP
headers or vendor-defined socket options, as listed
in the section on /"Exports below.
Exports
default
INADDR_ALLHOSTS_GROUP INADDR_ALLRTRS_GROUP INADDR_ANY
24/Aug/1997 perl 5.005, patch 03 8
lib::Net::Inet(User Contributed Perl Documentatilib::Net::Inet(3)
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_IPIP IPPROTO_MAX
IPPROTO_PUP IPPROTO_RAW IPPROTO_RSVP IPPROTO_TCP
IPPROTO_TP IPPROTO_UDP htonl htons inet_addr
inet_aton inet_ntoa ntohl ntohs
exportable
DEFTTL ICMP_ADVLENMIN ICMP_ECHO ICMP_ECHOREPLY
ICMP_INFOTYPE 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_BADCLASS IN_CLASSA IN_CLASSA_HOST IN_CLASSA_MAX
IN_CLASSA_NET IN_CLASSA_NSHIFT IN_CLASSA_SUBHOST
IN_CLASSA_SUBNET IN_CLASSA_SUBNSHIFT IN_CLASSB
IN_CLASSB_HOST IN_CLASSB_MAX IN_CLASSB_NET
IN_CLASSB_NSHIFT IN_CLASSB_SUBHOST IN_CLASSB_SUBNET
IN_CLASSB_SUBNSHIFT IN_CLASSC IN_CLASSC_HOST
IN_CLASSC_MAX IN_CLASSC_NET IN_CLASSC_NSHIFT
IN_CLASSD IN_CLASSD_HOST IN_CLASSD_NET
IN_CLASSD_NSHIFT IN_EXPERIMENTAL IN_LOOPBACKNET
IN_MULTICAST IPFRAGTTL IPOPT_CIPSO IPOPT_CLASS
IPOPT_CONTROL IPOPT_COPIED IPOPT_DEBMEAS IPOPT_EOL
IPOPT_LSRR IPOPT_MINOFF IPOPT_NOP IPOPT_NUMBER
IPOPT_OFFSET IPOPT_OLEN IPOPT_OPTVAL IPOPT_RESERVED1
IPOPT_RESERVED2 IPOPT_RIPSO_AUX 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 MAX_IPOPTLEN MINTTL SUBNETSHIFT
pack_sockaddr_in unpack_sockaddr_in
24/Aug/1997 perl 5.005, patch 03 9
lib::Net::Inet(User Contributed Perl Documentatilib::Net::Inet(3)
tags The following :tags are in %EXPORT_TAGS, with the
associated exportable values as listed:
:sockopts 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 pack_sockaddr_in unpack_sockaddr_in inet_ntoa
inet_aton inet_addr htonl ntohl htons ntohs
ICMP_INFOTYPE IN_BADCLASS IN_EXPERIMENTAL
IN_MULTICAST IPOPT_CLASS IPOPT_COPIED
IPOPT_NUMBER
:icmpvalues
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
IPOPT_CIPSO IPOPT_CONTROL IPOPT_DEBMEAS
IPOPT_EOL IPOPT_LSRR IPOPT_MINOFF IPOPT_NOP
IPOPT_OFFSET IPOPT_OLEN IPOPT_OPTVAL
IPOPT_RESERVED1 IPOPT_RESERVED2 IPOPT_RIPSO_AUX
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 MAX_IPOPTLEN
:iptosvalues
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
DEFTTL INADDR_ALLHOSTS_GROUP
INADDR_ALLRTRS_GROUP INADDR_ANY INADDR_BROADCAST
24/Aug/1997 perl 5.005, patch 03 10
lib::Net::Inet(User Contributed Perl Documentatilib::Net::Inet(3)
INADDR_LOOPBACK INADDR_MAX_LOCAL_GROUP
INADDR_NONE INADDR_UNSPEC_GROUP IN_LOOPBACKNET
IPPORT_RESERVED IPPORT_USERRESERVED IPPROTO_EGP
IPPROTO_EON IPPROTO_GGP IPPROTO_HELLO
IPPROTO_ICMP IPPROTO_IDP IPPROTO_IGMP IPPROTO_IP
IPPROTO_IPIP IPPROTO_MAX IPPROTO_PUP IPPROTO_RAW
IPPROTO_RSVP IPPROTO_TCP IPPROTO_TP IPPROTO_UDP
IPFRAGTTL IPTTLDEC IPVERSION IP_DF IP_MAXPACKET
IP_MF IP_MSS MAXTTL MAX_IPOPTLEN MINTTL
:ipmulticast
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
:deprecated
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_CLASSA IN_CLASSB IN_CLASSC
IN_CLASSD IPPORT_TIMESERVER SUBNETSHIFT
:ALL All of the above exportable items.
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 strictly 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:
24/Aug/1997 perl 5.005, patch 03 11
lib::Net::Inet(User Contributed Perl Documentatilib::Net::Inet(3)
($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>
24/Aug/1997 perl 5.005, patch 03 12
lib::Net::Inet(User Contributed Perl Documentatilib::Net::Inet(3)24/Aug/1997 perl 5.005, patch 03 13
