This is Info file pm.info, produced by Makeinfo version 1.68 from the input file bigpm.texi.  File: pm.info, Node: Net/Telnet/Cisco, Next: Net/Time, Prev: Net/Telnet, Up: Module List interact with a Cisco router **************************** NAME ==== Net::Telnet::Cisco - interact with a Cisco router SYNOPSIS ======== use Net::Telnet::Cisco; my $cs = Net::Telnet::Cisco->new( Host => '123.123.123.123' ); $cs->login( 'login', 'password' ); # Turn off paging my @cmd_output = $cs->cmd( 'terminal length 0' ); # Execute a command @cmd_output = $cs->cmd( 'show running-config' ); print @cmd_output; # Generate an error on purpose # This error handler prints the errmsg and continues. $cs->errmode( sub { print @_, "\n" } ); @cmd_output = $cs->cmd( 'asdf' ); # Bad command. print "-" x 30, "\n"; print "Last prompt: <", $cs->last_prompt, ">\n"; print "Last command: <", $cs->last_cmd, ">\n"; print "Last error: <", $cs->errmsg, ">\n"; print "Cmd output: <", @cmd_output, ">\n"; print "-" x 30, "\n"; # Try out enable mode if ( $cs->enable("enable_password") ) { @cmd_output = $cs->cmd('show privilege'); print "Cmd output: <", @cmd_output, ">\n"; } else { warn "Can't enable: " . $cs->errmsg; } $cs->close; DESCRIPTION =========== Net::Telnet::Cisco provides additional functionality to Net::Telnet for dealing with Cisco routers. Things you should know: The default cmd_prompt is /[\w().-]*[\$#>]\s?(?:\(enable\))?\s*$/, suitable for matching promtps like 'rtrname$ ', 'rtrname# ', and 'rtrname> (enable) '. cmd() parses router-generated error messages - the kind that begin with a '%' - and stows them in $obj->errmsg(), so that errmode can be used to perform automatic error-handling actions. FIRST ===== Before you use Net::Telnet::Cisco, you should probably have a good understanding of Net::Telnet, so perldoc Net::Telnet first, and then come back to Net::Telnet::Cisco to see where the improvements are. Some things are easier to accomplish with Net::SNMP. SNMP has three advantages: it's faster, handles errors better, and doesn't use any vtys on the router. SNMP does have some limitations, so for anything you can't accomplish with SNMP, there's Net::Telnet::Cisco. METHODS ======= New methods not found in Net::Telnet follow: enable - enter enabled mode $ok = $obj->enable; $ok = $obj->enable( $password ); This method changes privilege level to enabled mode, (i.e. root) If an argument is provided by the caller, it will be used as a password. enable() returns 1 on success and undef on failure. disable - leave enabled mode $ok = $obj->disable; This method exits the router's privileged mode. last_prompt - displays the last prompt matched by prompt() $match = $obj->last_prompt; last_prompt() will return " if the program has not yet matched a prompt. login - login to a router. $ok = $obj->login($username, $password); $ok = $obj->login(Name => $username, Password => $password, [Prompt => $match,] [Timeout => $secs,]); Net::Telnet::Cisco will correctly log into a router if the session begins with a password prompt (and ignores the login or username step entirely). AUTHOR ====== Joshua_Keroes@eli.net $Date: 2000/07/30 22:16:51 $ It would greatly amuse the author if you would send email to him and tell him how you are using Net::Telnet::Cisco. SEE ALSO ======== Net::Telnet, Net::SNMP COPYRIGHT ========= Copyright (c) 2000 Joshua Keroes, Electric Lightwave Inc. All rights reserved. This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself.  File: pm.info, Node: Net/Time, Next: Net/Traceroute, Prev: Net/Telnet/Cisco, Up: Module List time and daytime network client interface ***************************************** NAME ==== Net::Time - time and daytime network client interface SYNOPSIS ======== use Net::Time qw(inet_time inet_daytime); print inet_time(); # use default host from Net::Config print inet_time('localhost'); print inet_time('localhost', 'tcp'); print inet_daytime(); # use default host from Net::Config print inet_daytime('localhost'); print inet_daytime('localhost', 'tcp'); DESCRIPTION =========== `Net::Time' provides subroutines that obtain the time on a remote machine. inet_time ( [HOST [, PROTOCOL [, TIMEOUT]]]) Obtain the time on `HOST', or some default host if `HOST' is not given or not defined, using the protocol as defined in RFC868. The optional argument PROTOCOL should define the protocol to use, either `tcp' or `udp'. The result will be a time value in the same units as returned by time() or undef upon failure. inet_daytime ( [HOST [, PROTOCOL [, TIMEOUT]]]) Obtain the time on `HOST', or some default host if `HOST' is not given or not defined, using the protocol as defined in RFC867. The optional argument PROTOCOL should define the protocol to use, either `tcp' or `udp'. The result will be an ASCII string or undef upon failure. AUTHOR ====== Graham Barr COPYRIGHT ========= Copyright (c) 1995-1998 Graham Barr. All rights reserved. This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself.  File: pm.info, Node: Net/Traceroute, Next: Net/UDP, Prev: Net/Time, Up: Module List traceroute(1) functionality in perl *********************************** NAME ==== Net::Traceroute - traceroute(1) functionality in perl SYNOPSIS ======== use Net::Traceroute; $tr = Net::Traceroute->new(host=> "life.ai.mit.edu"); if($tr->found) { my $hops = $tr->hops; if($hops > 1) { print "Router was " . $tr->hop_query_host($tr->hops - 1, 1) . "\n"; } } DESCRIPTION =========== This module implements traceroute(1) functionality for perl5. It allows you to trace the path IP packets take to a destination. It is currently implemented as a parser around the system traceroute command. OVERVIEW ======== A new Net::Traceroute object must be created with the new method. Depending on exactly how the constructor is invoked, it may perform the traceroute immediately, or it may return a "template" object that can be used to set parameters for several subsequent traceroutes. Methods are available for accessing information about a given traceroute attempt. There are also methods that view/modify the options that are passed to the object's constructor. To trace a route, UDP packets are sent with a small TTL (time-to-live) field in an attempt to get intervening routers to generate ICMP TIME_EXCEEDED messages. CONSTRUCTOR =========== $obj = Net::Traceroute->new([base_port => $base_port,] [debug => $debuglvl,] [max_ttl => $max_ttl,] [host => $host,] [queries => $queries,] [query_timeout => $query_timeout,] [timeout => $timeout,]); $frob = $obj->new([options]); This is the constructor for a new Net::Traceroute object. If given host, it will actually perform the traceroute; otherwise it will return an empty template object. This can be used to setup a template object with some preset defaults for firing off multiple traceroutes. Given an existing Net::Traceroute object $obj as a template, you can call $obj->new() with the usual parameters. The same rules apply about defining host; that is, traceroute will be run if it is defined. You can always pass host => undef in the constructor call. To use a template objects to perform a traceroute, you invoke new on it and pass a host option. Possible options are: host - A host to traceroute to. If you don't set this, you get a Traceroute object with no traceroute data in it. The module always uses IP addresses internally and will attempt to lookup host names via inet_aton. *base_port* - Base port number to use for the UDP queries. Traceroute assumes that nothing is listening to port `base_port' to `base_port + (nhops - 1)' where nhops is the number of hops required to reach the destination address. Default is what the system traceroute uses (normally 33434). `Traceroute''s -p option. *debuglvl* - A number indicating how verbose debug information should be. Please include debug=>9 output in bug reports. *max_ttl* - Maximum number of hops to try before giving up. Default is what the system traceroute uses (normally 30). `Traceroute''s -m option. *queries* - Number of times to send a query for a given hop. Defaults to whatever the system traceroute uses (3 for most traceroutes). `Traceroute''s -q option. *query_timeout* - How many seconds to wait for a response to each query sent. Uses the system traceroute's default value of 5 if unspecified. `Traceroute''s -w option. timeout - Maximum time, in seconds, to wait for the traceroute to complete. If not specified, the traceroute will not return until the host has been reached, or traceroute counts to infinity (`max_ttl' * `queries' * `query_timeout'). Note that this option is implemented by Net::Traceroute, not the underlying traceroute command. METHODS ======= Controlling traceroute invocation --------------------------------- Each of these methods return the current value of the option specified by the corresponding constructor option. They will set the object's instance variable to the given value if one is provided. Changing an instance variable will only affect newly performed traceroutes. Setting a different value on a traceroute object that has already performed a trace has no effect. See the constructor documentation for information about each method/constructor option. base_port([PORT]) max_ttl([PORT]) queries([QUERIES]) query_timeout([TIMEOUT]) host([HOST]) timeout([TIMEOUT]) Obtaining information about a Trace ----------------------------------- These methods return information about a traceroute that has already been performed. Any of the methods in this section that return a count of something or want an Nth type count to identify something employ one based counting. stat Returns the status of a given traceroute object. One of TRACEROUTE_OK, TRACEROUTE_TIMEOUT, or TRACEROUTE_UNKNOWN (each defined as an integer). TRACEROUTE_OK will only be returned if the host was actually reachable. found Returns 1 if the host was found, undef otherwise. hops Returns the number of hops that it took to reach the host. hop_queries(HOP) Returns the number of queries that were sent for a given hop. This should normally be the same for every query. hop_query_stat(HOP, QUERY) Return the status of the given HOP's QUERY. The return status can be one of the following (each of these is actually an integer constant function defined in Net::Traceroute's export list): TRACEROUTE_OK Reached the host, no problems. TRACEROUTE_TIMEOUT This query timed out. TRACEROUTE_UNKNOWN Your guess is as good as mine. Shouldn't happen too often. TRACEROUTE_UNREACH_NET This hop returned an ICMP Network Unreachable. TRACEROUTE_UNREACH_HOST This hop returned an ICMP Host Unreachable. TRACEROUTE_UNREACH_PROTO This hop returned an ICMP Protocol unreachable. TRACEROUTE_UNREACH_NEEDFRAG Indicates that you can't reach this host without fragmenting your packet further. Shouldn't happen in regular use. TRACEROUTE_UNREACH_SRCFAIL A source routed packet was rejected for some reason. Shouldn't happen. TRACEROUTE_UNREACH_FILTER_PROHIB A firewall or similar device has decreed that your traffic is disallowed by administrative action. Suspect sheer, raving paranoia. TRACEROUTE_BSDBUG The destination machine appears to exhibit the 4.[23]BSD time exceeded bug. hop_query_host(HOP, QUERY) Return the dotted quad IP address of the host that responded to HOP's QUERY. hop_query_time(HOP, QUERY) Return the round trip time associated with the given HOP's query. If your system's traceroute supports fractional second timing, so will Net::Traceroute. BUGS ==== Net::Traceroute parses the output of the system traceroute command. As such, it may not work on your system. Support for more traceroute outputs (e.g. Windows, HPUX) could be done, although currently the code assumes there is "One true traceroute". The actual functionality of traceroute could also be implemented natively in perl or linked in from a C library. As of 0.7 (the first public release) I consider the interface stable. Violent changes to interface are always possible, but I will retain compatibility with this interface in future releases. SEE ALSO ======== traceroute(1) AUTHOR ====== Daniel Hagerty COPYRIGHT ========= Copyright 1998, 1999 Massachusetts Institute of Technology Permission to use, copy, modify, distribute, and sell this software and its documentation for any purpose is hereby granted without fee, provided that the above copyright notice appear in all copies and that both that copyright notice and this permission notice appear in supporting documentation, and that the name of M.I.T. not be used in advertising or publicity pertaining to distribution of the software without specific, written prior permission. M.I.T. makes no representations about the suitability of this software for any purpose. It is provided "as is" without express or implied warranty.  File: pm.info, Node: Net/UDP, Next: Net/UNIX, Prev: Net/Traceroute, Up: Module List UDP sockets interface module **************************** NAME ==== Net::UDP - UDP sockets interface module SYNOPSIS ======== use Net::Gen; # optional use Net::Inet; # optional use Net::UDP; DESCRIPTION =========== The `Net::UDP' module provides services for UDP communications over sockets. It is layered atop the `Net::Inet' and `Net::Gen' modules, which are part of the same distribution. Public Methods -------------- The following methods are provided by the `Net::UDP' module itself, rather than just being inherited from `Net::Inet' or `Net::Gen'. new Usage: $obj = new Net::UDP; $obj = new Net::UDP $desthost, $destservice; $obj = new Net::UDP \%parameters; $obj = new Net::UDP $desthost, $destservice, \%parameters; $obj = 'Net::UDP'->new(); $obj = 'Net::UDP'->new($desthost); $obj = 'Net::UDP'->new($desthost, $destservice); $obj = 'Net::UDP'->new(\%parameters); $obj = 'Net::UDP'->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 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, which `Net::UDP' inherits from `Net::Inet'. In particular, this means that if both a host and a service are given, that an object will only be returned if a connect() call was successful. 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 for details. PRINT Usage: $ok = $obj->PRINT(@args); $ok = print $tied_fh @args; This method, intended to be used with tied filehandles, behaves like one of two inherited methods from the `Net::Gen' class, depending on the setting of the object parameter unbuffered_output. If that parameter is false (the default), then the normal print() builtin is used. If the unbuffered_output parameter is true, then each print() operation will actually result in a call to the send method, requiring that the object be connected or that its message is in response to its last normal recv() (with a flags parameter of 0). The value of the $\ variable is ignored in that case, but the $, variable is still used if the `@args' array has multiple elements. READLINE Usage: $line_or_datagram = $obj->READLINE; $line_or_datagram = ; $line_or_datagram = readline(TIED_FH); @lines_or_datagrams = $obj->READLINE; @lines_or_datagrams = ; @lines_or_datagrams = readline(TIED_FH); This method, intended to be used with tied filehandles, behaves like one of two inherited methods from the `Net::Gen' class, depending on the setting of the object parameter unbuffered_input. If that parameter is false (the default), then this method does line-buffering of its input as defined by the current setting of the $/ variable. If the parameter is true, then the input records will be exact recv() datagrams, disregarding the setting of the $/ variable. Note that invoking the READLINE method in list context is likely to hang, since UDP sockets typically don't return EOF. Protected Methods ----------------- none. Known Socket Options -------------------- There are no object parameters registered by the `Net::UDP' module itself. Known Object Parameters ----------------------- The following object parameters are registered by the `Net::UDP' module (as distinct from being inherited from `Net::Gen' or `Net::Inet'): unbuffered_input If true, the READLINE operation on tied filehandles will return each recv() buffer as though it were a single separate line, independently of the setting of the $/ variable. The default is false, which causes the READLINE interface to return lines split at boundaries as appropriate for $/. (The READLINE method for tied filehandles is the `' operation.) Note that calling the READLINE method in list context is likely to hang. unbuffered_output If true, the PRINT operation on tied filehandles will result in calls to the send() builtin rather than the print() builtin, as described in `' in this node above. The default is false, which causes the PRINT method to use the print() builtin. unbuffered_IO This object parameter's value is unreliable on getparam or getparams method calls. It is provided as a handy way to set both the unbuffered_output and unbuffered_input object parameters to the same value at the same time during new calls. TIESCALAR support ----------------- Tieing of scalars to a UDP handle is supported by inheritance from the TIESCALAR method of `Net::Gen'. That method only succeeds if a call to a new method results in an object for which the isconnected method returns true, which is why it is mentioned in regard to this module. Example: tie $x,'Net::UDP',0,'daytime' or die "tie to Net::UDP: $!"; $x = "\n"; $x = "\n"; print $y if defined($y = $x); untie $x; This is an expensive re-implementation of date on many machines. Each assignment to the tied scalar is really a call to the put method (via the STORE method), and each read from the tied scalar is really a call to the READLINE method (via the FETCH method). TIEHANDLE support ----------------- As inherited from `Net::Inet' and `Net::Gen', with the addition of unbuffered I/O options for the READLINE and PRINT methods. Exports ------- none THREADING STATUS ================ 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.) SEE ALSO ======== Net::Inet(3), Net::Gen(3) AUTHOR ====== Spider Boardman  File: pm.info, Node: Net/UNIX, Next: Net/UNIX/Server, Prev: Net/UDP, Up: Module List UNIX-domain sockets interface module ************************************ NAME ==== Net::UNIX - UNIX-domain sockets interface module SYNOPSIS ======== use Net::Gen; # optional use Net::UNIX; DESCRIPTION =========== The `Net::UNIX' module provides services for UNIX-domain socket communication. It is layered atop the `Net::Gen' module, which is part of the same distribution. Public Methods -------------- The following methods are provided by the `Net::UNIX' module itself, rather than just being inherited from `Net::Gen'. new Usage: $obj = new Net::UNIX; $obj = new Net::UNIX $pathname; $obj = new Net::UNIX \%parameters; $obj = new Net::UNIX $pathname, \%parameters; $obj = 'Net::UNIX'->new(); $obj = 'Net::UNIX'->new($pathname); $obj = 'Net::UNIX'->new(\%parameters); $obj = 'Net::UNIX'->new($pathname, \%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 a pathname is given, an object will be returned only if a connect() call was successful. 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 for details. init Usage: return undef unless $self = $self->init; return undef unless $self = $self->init(\%parameters); return undef unless $self = $self->init($pathname); return undef unless $self = $self->init($pathname, \%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($pathname); $ok = $obj->bind($pathname,\%newparameters); Updates the object with the supplied new parameters (if supplied), then sets up the srcaddrlist object parameter with the specified $pathname argument (if supplied), and then returns the value from the inherited bind method. Example: $ok = $obj->bind('/tmp/.fnord'); # start a service on /tmp/.fnord connect Usage: $ok = $obj->connect; $ok = $obj->connect($pathname); $ok = $obj->connect($pathname,\%newparameters); Attempts to establish a connection for the object. If the `newparams' argument is specified, it will be used to update the object parameters. Then, if the $pathname argument is specified, it will be used to set the dstaddrlist object parameter. Finally, the result of a call to the inherited connect method will be returned. format_addr Usage: $string = $obj->format_addr($sockaddr); $string = format_addr Module $sockaddr; Returns a formatted representation of the socket address. This is normally just a pathname, or the constant string ". PRINT Usage: $ok = $obj->PRINT(@args); $ok = print $tied_fh @args; This method, intended to be used with tied filehandles, behaves like one of two inherited methods from the `Net::Gen' class, depending on the setting of the object parameter unbuffered_output and whether the socket is a SOCK_STREAM (stream) socket or a datagram socket (the default). If that parameter is false (the default) or the socket is a stream socket, then the normal print() builtin is used. If the unbuffered_output parameter is true for a datagram socket, then each print() operation will actually result in a call to the send method. The value of the $\ variable is ignored in that case, but the $, variable is still used if the `@args' array has multiple elements. READLINE Usage: $line_or_datagram = $obj->READLINE; $line_or_datagram = ; $line_or_datagram = readline(TIED_FH); @lines_or_datagrams = $obj->READLINE; @lines_or_datagrams = ; @lines_or_datagrams = readline(TIED_FH); This method, intended to be used with tied filehandles, behaves like one of two inherited methods from the `Net::Gen' class, depending on the setting of the object parameter unbuffered_input and whether the socket is a SOCK_STREAM (stream) socket or a datagram socket (the default). If that parameter is false (the default) or the socket is a stream socket, then this method does line-buffering of its input as defined by the current setting of the $/ variable. If the unbuffered_input parameter is true for a datagram socket, then the input records will be exact recv() datagrams, disregarding the setting of the $/ variable. Protected Methods ----------------- [See the description in `"Protected Methods"', *Note Net/Gen: Net/Gen, for my definition of protected methods in Perl.] None. Known Socket Options -------------------- There are no socket options known to the `Net::UNIX' module itself. Known Object Parameters ----------------------- The following object parameters are registered by the `Net::UNIX' module (as distinct from being inherited from `Net::Gen'): unbuffered_input If true, the READLINE operation on tied filehandles which are datagram sockets will return each recv() buffer as though it were a single separate line, independently of the setting of the $/ variable. The default is false, which causes the READLINE interface to return lines split at boundaries as appropriate for $/. (The READLINE method for tied filehandles is the `' operation.) unbuffered_output If true, the PRINT operation on tied filehandles which are datagram sockets will result in calls to the send() builtin rather than the print() builtin, as described in `' in this node above. The default is false, which causes the PRINT method to use the print() builtin. unbuffered_IO This object parameter's value is unreliable on getparam or getparams method calls. It is provided as a handy way to set both the unbuffered_output and unbuffered_input object parameters to the same value at the same time during new calls. TIESCALAR --------- Tieing of scalars to a UNIX-domain handle is supported by inheritance from the TIESCALAR method of `Net::Gen'. That method only succeeds if a call to a new method results in an object for which the isconnected method returns a true result. Thus, for `Net::UNIX', TIESCALAR will not succeed unless the `pathname' argument is given. Each assignment to the tied scalar is really a call to the put method (via the STORE method), and each read from the tied scalar is really a call to the READLINE method (via the FETCH method). TIEHANDLE support ----------------- As inherited from `Net::Gen', with the addition of unbuffered datagram I/O options for the FETCH, READLINE, and PRINT methods. Non-Method Subroutines ---------------------- pack_sockaddr_un Usage: $connect_address = pack_sockaddr_un($family, $pathname); $connect_address = pack_sockaddr_un($pathname); Returns the packed `struct sockaddr_un' corresponding to the provided $family and $pathname arguments. The $family argument as assumed to be `AF_UNIX' if it is missing. This is otherwise the same as the pack_sockaddr_un() routine in the Socket module. unpack_sockaddr_un Usage: ($family, $pathname) = unpack_sockaddr_un($connected_address); $pathname = unpack_sockaddr_un($connected_address); Returns the address family and pathname (if known) from the supplied packed `struct sockaddr_un'. This is the inverse of pack_sockaddr_un(). It differs from the implementation in the Socket module in its return of the `$family' value, and in that it trims the returned pathname at the first null character. Exports ------- default None. exportable pack_sockaddr_un unpack_sockaddr_un tags The following *:tags* are available for grouping exportable items: :routines pack_sockaddr_un unpack_sockaddr_un :ALL All of the above exportable items. THREADING STATUS ================ 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.) SEE ALSO ======== Net::Gen(3), Net::UNIX::Server(3) AUTHOR ====== Spider Boardman  File: pm.info, Node: Net/UNIX/Server, Next: Net/Wake, Prev: Net/UNIX, Up: Module List UNIX-domain sockets interface module for listeners ************************************************** NAME ==== Net::UNIX::Server - UNIX-domain sockets interface module for listeners SYNOPSIS ======== use Net::Gen; # optional use Net::UNIX; # optional use Net::UNIX::Server; DESCRIPTION =========== The `Net::UNIX::Server' module provides additional services for UNIX-domain socket communication. It is layered atop the `Net::UNIX' and `Net::Gen' modules, which are part of the same distribution. Public Methods -------------- The following methods are provided by the `Net::UNIX::Server' module itself, rather than just being inherited from `Net::UNIX' or `Net::Gen'. new Usage: $obj = new Net::UNIX::Server; $obj = new Net::UNIX::Server $pathname; $obj = new Net::UNIX::Server $pathname, \%parameters; $obj = 'Net::UNIX::Server'->new(); $obj = 'Net::UNIX::Server'->new($pathname); $obj = 'Net::UNIX::Server'->new($pathname, \%parameters); Returns a newly-initialised object of the given class. This is much like the regular new methods of other modules in this distribution, except that it does a bind rather than a connect, and it does a listen. Unless specified otherwise with a type object parameter, the underlying socket will be a datagram socket (`SOCK_DGRAM'). 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 for details. See *Note Net/TCP/Server: Net/TCP/Server, for an example of running a server. The differences are only in the module names and the fact that UNIX-domain sockets bind to a pathname rather than to a port number. Of course, that example is for stream (`type = SOCK_STREAM') sockets rather than for datagrams. UNIX-domain datagram sockets don't need to do an accept() (and can't where I've tested this code), and can't answer back to their clients unless those clients have also bound to a specific path name. init Usage: return undef unless $self = $self->init; return undef unless $self = $self->init(\%parameters); return undef unless $self = $self->init($pathname); return undef unless $self = $self->init($pathname, \%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. Protected Methods ----------------- [See the description in `"Protected Methods"', *Note Net/Gen: Net/Gen, for my definition of protected methods in Perl.] None. Known Socket Options -------------------- There are no socket options known to the `Net::UNIX::Server' module itself. Known Object Parameters ----------------------- There are no object parameters registered by the `Net::UNIX::Server' module itself. Exports ------- default None. exportable None. tags The following *:tags* are available for grouping exportable items: :ALL All of the above exportable items. THREADING STATUS ================ 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.) SEE ALSO ======== Net::UNIX(3), Net::Gen(3) AUTHOR ====== Spider Boardman  File: pm.info, Node: Net/Wake, Next: Net/Whois, Prev: Net/UNIX/Server, Up: Module List A package to send packets to power on computers. ************************************************ NAME ==== Net::Wake - A package to send packets to power on computers. SYNOPSIS ======== To send a wake-on-lan packet via UDP: Net::Wake::by_udp('192.168.1.2', '00:00:87:A0:8A:D2'); DESCRIPTION =========== This package sends wake-on-lan packets to turn on machines that are wake-on-lan capable. For now there is only one function in this package: Net::Wake::by_udp(host, mac_address, [port]); One can omit the colons in the mac_address, but not leading zeros. SEE ALSO ======== http://www.pc.ibm.com/us/infobrf/iblan.html http://www.nec-computers.com/about/tech/wp-wakeon.html COPYRIGHT ========= Copyright 1999 Clinton Wong This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself.  File: pm.info, Node: Net/Whois, Next: Net/XWhois, Prev: Net/Wake, Up: Module List Get and parse "whois" domain data from InterNIC *********************************************** NAME ==== Net::Whois - Get and parse "whois" domain data from InterNIC SYNOPSIS ======== Note that all fields except "name" and "tag" may be undef because "whois" information is erratically filled in. use Net::Whois; use Carp; my $w = new Net::Whois::Domain $dom or die "Can't connect to Whois server\n; unless ($w->ok) { croak "No match for $dom";} print "Domain: ", $w->domain, "\n"; print "Name: ", $w->name, "\n"; print "Tag: ", $w->tag, "\n"; print "Address:\n", map { " $_\n" } $w->address; print "Country: ", $w->country, "\n"; print "Name Servers:\n", map { " $$_[0] ($$_[1])\n" } @{$w->servers}; my ($c, $t); if ($c = $w->contacts) { print "Contacts:\n"; for $t (sort keys %$c) { print " $t:\n"; print map { "\t$_\n" } @{$$c{$t}}; } } print "Record created:", $w->record_created ; print "Record updated:", $w->record_updated ; DESCRIPTION =========== Net::Whois::Domain new() attempts to retrieve and parse the given domain's "whois" information from the InterNIC (whois.internic.net). If the server could not be contacted, is too busy, or otherwise does not process the query then the constructor does not return a reference and your object is undefined. If the constructor returns a reference, that reference can be used to access the various attributes of the domains' whois entry assuming that there was a match. The member function ok returns 1 if a match 0 if no match. Note that the Locale::Country module (part of the Locale-Codes distribution) is used to recognize spelled-out country names; if that module is not present, only two-letter country abbreviations will be recognized. The server consulted is "whois.internic.net". You can only get .org, .edu, .net, .com domains from Internic. Other whois servers for other Top-Level-Domains (TLD) return information in a different syntax and are not supported at this time. Also, only queries for domains are valid. Querying for a network will fail utterly since those are not kept in the whois.internic.net server (a future enhancement will add a network lookup function). Querying for NIC handles won't work since they have a different return syntax than a domain. Domains other than those listed won't work they're not in the server. A future enhancment planned will send the query to the appropriate server based on its TLD. AUTHOR ====== Originally written by Chip Salzenberg (chip@pobox.com) in April of 1997 for Idle Communications, Inc. In September of 1998 Dana Hudes (dhudes@hudes.org) found this but it was broken and he needed it so he fixed it. In August, 1999 Dana and Chip agreed to become co-maintainers of the module. Dana released a new version of Net::Whois to CPAN and resumed active development. COPYRIGHT ========= This module is free software; you can redistribute it and/or modify it under the same terms as Perl itself. If you make modifications, the author would like to know so that they can be incorporated into future releases.  File: pm.info, Node: Net/XWhois, Next: Net/Z3950, Prev: Net/Whois, Up: Module List Whois Client Interface for Perl5. ********************************* NAME ==== Net::XWhois - Whois Client Interface for Perl5. SYNOPSIS ======== use Net::XWhois; $whois = new Net::XWhois Domain => "vipul.net" ; $whois = new Net::XWhois Domain => "bit.ch", Server => "domreg.nic.ch", Retain => 1, Parser => { nameservers => 'nserver:\s+(\S+)', }; DESCRIPTION =========== The Net::XWhois class provides a generic client framework for doing Whois queries and parsing server response. The class maintains an array of whois servers and associated lists of top level domains they serve for transparently selecting servers appropriate for different queries. The server details are, therefore, hidden from the user and "vipul.net" (from InterNIC), gov.ru (from RIPE) and "bit.ch" (from domreg.nic.ch) are queried in the same manner. This behaviour can be overridden by specifying different bindings at object construction or by registering associations with the class. See `"register_associations()"' in this node and `"new()"' in this node. One of the more important features of this module is to enable the design of consistent and predictable interfaces to incompatible whois response formats. The Whois RFC (954) does not define a template for presenting server data; consequently there is a large variation in layout styles as well as content served across servers. To overcome this, Net::XWhois maintains another set of tables - parsing rulesets - for a few, popular response formats. (See `"%PARSERS"' in this node). These parsing tables contain section names (labels) together with regular expressions that match the corresponding section text. The section text is accessed "via" labels which are available as data instance methods at runtime. By following a consistent nomenclature for labels, semantically related information encoded in different formats can be accessed with the same methods. CONSTRUCTOR =========== new () Creates a Net::XWhois object. Takes an optional argument, a hash, that specifies the domain name to be queried. Calls lookup() if a name is provided. The argument hash can also specify a whois server, a parsing rule-set or a parsing rule-set format. (See `"personality()"' in this node). Omitting the argument will create an "empty" object that can be used for accessing class data. personality () Alters an object's personality. Takes a hash with following arguments. (Note: These arguments can also be passed to the constructor). Domain Domain name to be queried. Server Server to query. Parser Parsing Rule-set. See `"%PARSERS"' in this node. Parser => { name => 'domain:\s+(\S+)\n', nameservers => 'nserver:\s+(\S+)', contact_emails => 'e-mail:\s+(\S+\@\S+)', }; Format A pre-defined parser format like INTERNIC, INTERNIC_FORMAT, RIPE, RIPE_CH, JAPAN etc. Format => 'INTERNIC_CONTACT', Nocache Force XWhois to ignore the cached records. Error Determines how a network connection error is handled. By default Net::XWhois will croak() if it can't connect to the whois server. The Error attribute specifies a function call name that will be invoked when a network connection error occurs. Possible values are croak, carp, confess (imported from Carp.pm) and ignore (a blank function provided by Net::XWhois). You can, of course, write your own function to do error handling, in which case you'd have to provide a fully qualified function name. Example: main::logerr. Timeout Timeout value for establishing a network connection with the server. The default value is 60 seconds. CLASS DATA & ACCESS METHODS =========================== %PARSERS An associative array that contains parsing rule-sets for various response formats. Keys of this array are format names and values are hash refs that contain section labels and corresponding parser code. The parser code can either be a regex or a reference to a subroutine. In the case of a subroutine, the whois 'response' information is available to the sub in $_[0]. Parsers can be added and extended with the register_parser() method. Also see `Data Instance Methods' in this node. my %PARSERS = ( INTERNIC => { contact_tech => 'Technical Contact.*?\n(.*?)(?=\... contact_zone => 'Zone Contact.*?\n(.*?)(?=\s*\n[... contact_billing => 'Billing Contact.*?\n(.*?)(?=\s*... contact_emails => \&example_email_parser }, { etc. ... }, ); sub example_email_parser { # Note that the default internal implemenation for # the INTERNIC parser is not a user-supplied code # block. This is just an instructive example. my @matches = $_[0] =~ /(\S+\@\S+)/sg; return @matches; } See XWhois.pm for the complete definition of %PARSERS. %ASSOC %ASSOC is a table that associates server names with response formats and the top-level domains they serve. You'd need to modity this table if you wish to extend the module's functionality to handle a new set of domain names. Or alter existing information. register_association() provides an interface to this array. See XWhois.pm for the complete definition. %ASSOC = ( 'whois.internic.net' => [ INTERNIC, [ qw/com net org/ ] ], 'whois.nic.net.sg' => [ RIPE, [ qw/sg/ ] ], 'whois.aunic.net' => [ RIPE, [ qw/au/ ] ] register_parser() Extend, modify and override entries in %PARSERS. Accepts a hash with three keys - Name, Retain and Parser. If the format definition for the specified format exists and the Retain key holds a true value, the keys from the specified Parser are added to the existing definition. A new definition is created when Retain is false/not specified. my $w = new Net::Whois; $w->register_parser ( Name => "INTERNIC", Retain => 1, Parser => { creation_time => 'created on (\S*?)\.\n', some_randome_entity => \&random_entity_subroutine }; Instructions on how to create a workable random_entity_subroutine are availabe in the I<%PARSERS> description, above. register_association() Override and add entries to %ASSOC. Accepts a hash that contains representation specs for a whois server. The keys of this hash are server machine names and values are list-refs to the associated response formats and the top-level domains handled by the servers. See Net/XWhois.pm for more details. my $w = new Net::XWhois; $w->register_association ( 'whois.aunic.net' => [ RIPE, [ qw/au/ ] ] ); register_cache() By default, Net::XWhois caches all whois responses and commits them, as separate files, to /tmp/whois. register_cache () gets and sets the cache directory. Setting to "undef" will disable caching. $w->register_cache ( "/some/place/else" ); $w->register_cache ( undef ); OBJECT METHODS ============== *Data Instance Methods* Access to the whois response data is provided via AUTOLOADED methods specified in the Parser. The methods return scalar or list data depending on the context. Internic Parser provides the following methods: name() Domain name. status() Domain Status when provided. When the domain is on hold, this method will return "On Hold" string. nameservers() Nameservers along with their IPs. registrant Registrant's name and address. contact_admin() Administrative Contact. contact_tech() Technical Contact. contact_zone() Zone Contact. contact_billing() Billing Contact. contact_emails() List of email addresses of contacts. contact_handles() List of contact handles in the response. Contact and Domain handles are valid query data that can be used instead of contact and domain names. domain_handles() List of domain handles in the response. Can be used for sorting out reponses that contain multiple domain names. lookup() Does a whois lookup on the specified domain. Takes the same arguments as new(). my $w = new Net::XWhois; $w->lookup ( Domain => "perl.com" ); print $w->response (); EXAMPLES ======== Look at example programs that come with this package. "whois" is a replacement for the standard RIPE/InterNIC whois client. "creation" overrides the Parser value at object init and gets the Creation Time of an InterNIC domain. "creation2" does the same thing by extending the Class Parser. "contacts" queries and prints information about domain's Tech/Billing/Admin contacts. contribs/ containts parsers for serveral whois servers, which have not been patched into the module. AUTHOR ====== Vipul Ved Prakash THANKS ====== Curt Powell , Matt Spiers , Richard Dice , Robert Chalmers for patches, bug-reports and many cogent suggestions. MAILING LIST ============ Net::XWhois development has moved to the sourceforge mailing, xwhois-devel@lists.sourceforge.net. Please send all Net::XWhois related communication directly to the list address. The subscription interface is at: http://lists.sourceforge.net/mailman/listinfo/xwhois-devel COPYRIGHT ========= Copyright (c) 1998-2000 Vipul Ved Prakash. All rights reserved. This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself.  File: pm.info, Node: Net/Z3950, Next: Net/Z3950/APDU, Prev: Net/XWhois, Up: Module List Perl extension for talking to Z39.50 servers. ********************************************* NAME ==== Net::Z3950 - Perl extension for talking to Z39.50 servers. SYNOPSIS ======== (This code blocks in reads: see below for sample non-blocking code which allows multiple servers to be searched in parallel.) use Net::Z3950; $conn = new Net::Z3950::Connection('server.host.name', 210); $rs = $conn->search('au=kernighan or su=unix'); foreach $rec ($rs->records()) { print $rec->render(); } DESCRIPTION =========== This module provides a Perl interface to the Z39.50 information retrieval protocol (aka. ISO 23950), a mature and powerful protocol used in application domains as diverse as bibliographic information, geo-spatial mapping, museums and other cultural heritage information, and structured vocabulary navigation. Two basic approaches are possible to building clients with this module: * The simple synchronous approach considers blocking reads acceptable, and therefore allows a straightforward style of imperative programming. This approach is suitable for clients which only talk to one server at a time, and is exemplified by the code in the SYNOPSIS section above. * The more complex asynchronous approach, appropriate for clients which multiplex simultaneous connections, requires a slightly less familiar event-driven programming style, as exemplified in the ASYNCHRONOUS SYNOPSIS section below. (The simpler synchronous interface functions are implemented as a thin layer on top of the asynchronous functions.) ASYNCHRONOUS SYNOPSIS ===================== (This code does not block in reads, and so is suitable for broadcast clients which search multiple servers simultaneously: see below for simpler sample code that blocks in reads.) ### No point filling this in until we have it working. FUNCTIONS ========= The `Net::Z3950' module itself provides very few functions: most of the functionality is provided by the daughter modules included by `Net::Z3950' - `Net::Z3950::Manager', `Net::Z3950::Connection', etc. errstr() -------- $errcode = $conn->errcode(); $errmsg = Net::Z3950::errmsg($errcode); print "error $errcode ($errmsg)\n"; Returns an English-language string describing the error indicated by the Z39.50 BIB-1 diagnostic error code *$errcode*. opstr() ------- $str = Net::Z3950::opstr($conn->errop()); print "error occurred in $str\n"; Returns an English-language string describing the operation indicated by the argument, which must be one of the `Net::Z3950::Op::*' constants described in the documentation for the `Net::Z3950::Connection' class's op() method. AUTHOR ====== Mike Taylor First version Tuesday 23rd May 2000. SEE ALSO ======== This module is built on Index Data's Yaz (Yet Another Z39.50) toolkit, which is freely available at http://indexdata.dk/yaz/ Index Data also provide a variety of other useful Z39.50 software including the free server/database Zebra, the commercial server/database Z'mbol, a Tcl interface to Z39.50 called Ir/Tcl, and a free web-to-Z39.50 gateway called Zap. See their home page at http://indexdata.dk/ The best source of information about Z39.50 itself is the official Mainenance Agency at http://lcweb.loc.gov/z3950/agency/