Net::Inet - Internet socket interface module use Net::Gen; # optional use Net::Inet; 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
Usage: $obj = new Net::Inet; $obj = new Net::Inet $desthost, $destservice; $obj = new Net::Inet \%parameters; $obj = new Net::Inet $desthost, $destservice, \%parameters; $obj = 'Net::Inet'->new(); $obj = 'Net::Inet'->new($desthost, $destservice); $obj = 'Net::Inet'->new(\%parameters); $obj = 'Net::Inet'->new($desthost, $destservice, \%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, or if the object is non-blocking and a connect() call is in progress. The examples above show the indirect object syntax which many prefer, as well as the guaranteed-to-be-safe static method call. There are occasional problems with the indirect object syntax, which tend to be rather obscure when encountered. See <URL:http://www.rosat.mpe-garching.mpg.de/mailing-lists/perl-porters/1998-01/msg01674.html> for details. Usage: return undef unless $self->init; return undef unless $self->init(\%parameters); return undef unless $self->init($desthost, $destservice); return undef unless $self->init($desthost, $destservice, \%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. Usage: $ok = $obj->bind; $ok = $obj->bind($lclhost, $lclservice); $ok = $obj->bind($lclhost, $lclservice, \%parameters); Sets up the `srcaddrlist' object parameter with the specified $lclhost and $lclservice 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 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. 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. 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. 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. 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. 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.) There are also various accessor methods for the object parameters. See the Accessors entry in the Net::Gen manpage for calling details. See the section on "Known Object Parameters" below for those defined by this class.

Protected Methods
[See the note in the Protected Methods entry 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: 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. Used the same way as with `Net::Gen', but has a handler attached to keep it in sync with `IPproto'. 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. 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. 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). 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). 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. 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. The local IP address stashed by the `getsockinfo' method after a successful bind() or connect() call. The local hostname stashed by the `getsockinfo' method after a successful bind() or connect(), as resolved from the `lcladdr' object parameter. The local port number stashed by the `getsockinfo' method after a successful bind() or connect() call. The local service name stashed by the `getsockinfo' method after a successful bind() or connect(), as resolved from the `lclport' object parameter. The remote IP address stashed by the `getsockinfo' method after a successful connect() call. The remote hostname stashed by the `getsockinfo' method after a successful connect() call, as resolved from the `remaddr' object parameter. The remote port number stashed by the `getsockinfo' method after a successful connect() call. The remote service name stashed by the `getsockinfo' method after a successful connect() call, as resolved from the `remport' object parameter.

Non-Method Subroutines
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. 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 of being unable to handle "255.255.255.255", so I didn't.) 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. As you'd expect, I think. 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). 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 (and might not be AF_INET). 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 the `INADDR_ANY' result described in the INADDR_ANY entry in the Socket manpage. 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. 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
`INADDR_ALLHOSTS_GROUP' `INADDR_ALLRTRS_GROUP' `INADDR_ANY' `INADDR_BROADCAST' `INADDR_LOOPBACK' `INADDR_MAX_LOCAL_GROUP' `INADDR_NONE' `INADDR_UNSPEC_GROUP' `IPPORT_RESERVED' `IPPORT_USERRESERVED' `IPPORT_DYNAMIC' `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' `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' The following :tags are in `%EXPORT_TAGS', with the associated exportable values as listed: `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' `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' `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' `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' `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' `DEFTTL' `INADDR_ALLHOSTS_GROUP' `INADDR_ALLRTRS_GROUP' `INADDR_ANY' `INADDR_BROADCAST' `INADDR_LOOPBACK' `INADDR_MAX_LOCAL_GROUP' `INADDR_NONE' `INADDR_UNSPEC_GROUP' `IN_LOOPBACKNET' `IPPORT_RESERVED' `IPPORT_USERRESERVED' `IPPORT_DYNAMIC' `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' `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' `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 of the above exportable items. 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. This module has been tested with threaded perls, and should be as thread-safe as perl itself. (As of 5.005_03 and 5.005_57, that's not all that safe just yet.) Net::Gen(3), Net::TCP(3), Net::UDP(3) Spider Boardman <spider@Orb.Nashua.NH.US>