|
|
Net::Gen - generic sockets interface handling
use Net::Gen;
The Net::Gen module provides basic services for handling
socket-based communications. It supports no particular protocol
family directly, however, so it is of direct use primarily to
implementors of other modules. To this end, several housekeeping
functions are provided for the use of derived classes, as well as
several inheritable methods. The Net::Gen class does inherit
from IO::Handle, thus making its methods available. See
IO::Handle::METHODS
for details on those methods. However, some
of those methods are overridden, so be sure to check the methods
described below to be sure. (In particular, the fcntl and ioctl
methods are overridden.)
Also provided in this distribution are
Net::Inet,
Net::TCP,
Net::TCP::Server,
Net::UDP,
Net::UNIX,
and
Net::UNIX::Server,
which are layered atop Net::Gen.
The public methods are listed alphabetically below. Here is an indication of their functional groupings:
new, new_from_fd, new_from_fh, init, checkparams,
open, connect, bind, listen
setparams, setparam, delparams, delparam, getparams,
getparam, param_saver
unbind, condition, getsopt, getropt, setsopt, setropt,
fcntl, ioctl
isopen, isconnected, isbound, didlisten, fhvec, getfh,
fileno
SEND, PRINT, PRINTF, RECV, READLINE, READ, GETC,
WRITE, CLOSE, EOF, BINMODE, FILENO,
TIEHANDLE
Any of the keys known to the getparam and setparams methods
may be used as an accessor function. See Known Object Parameters
below, and the related sections in the derived classes. For an example,
see blocking, below.
The descriptions, listed alphabetically:
Usage:
$newobj = $obj->accept;
Returns a new object in the same class as the given object if an
accept() call succeeds, and undef otherwise. If the accept()
call succeeds, the new object is marked as being open, connected,
and bound. This can fail unexpectedly if the listening socket is
non-blocking or if the object has a timeout parameter. See the
discussion of non-blocking sockets and timeouts in connect below.
Usage:
$ok = $obj->bind;
Makes a call to the bind() builtin on the filehandle associated
with the object. The arguments to bind() are determined from the
current parameters of the object. First, if the filehandle has
previously been bound or connected, it is closed. Then, if it is
not currently open, a call to the open method is made. If all
that works (which may be a no-op), then the following list of
possible values is tried for the bind() builtin: First, the
srcaddrlist object parameter, if its value is an array
reference. The elements of the array are tried in order until a
bind() succeeds or the list is exhausted. Second, if the
srcaddrlist parameter is not set to an array reference, if the
srcaddr parameter is a non-null string, it will be used.
Finally, if neither srcaddrlist nor srcaddr is suitably
set, the AF parameter will be used to construct a sockaddr
structure which will be mostly zeroed, and the bind() will be
attempted with that. If the bind() fails, undef will be
returned at this point. Otherwise, a call to the getsockinfo
method will be made, and then the value from a call to the
isbound method will be returned.
If all that seems too confusing, don't worry. Most clients will
never need to do an explicit bind call, anyway. If you're
writing a server or a privileged client which does need to bind
to a particular local port or address, and you didn't understand
the foregoing discussion, you may be in trouble. Don't panic
until you've checked the discussion of binding in the derived
class you're using, however.
Usage:
binmode(TIEDFH);
A no-op provided for the tied file handle support of perl 5.005_57.
The sockets managed by this module are always set binmode() anyway.
Usage:
$isblocking = $obj->blocking;
$oldblocking = $obj->blocking($newvalue);
The blocking method is an example of an accessor method. The
above usage examples are (effectively) equivalent to the following code
snippets, respectively:
$isblocking = $obj->getparam('blocking');
$oldblocking = $obj->getparam('blocking');
$obj->setparams({blocking=>$newvalue});
The getparam method call is skipped if the accessor method was
called in void context.
Usage:
$ok = $obj->checkparams;
Verifies that all previous parameter assignments are valid.
(Normally called only via the init method, rather than
directly.)
Usage:
$ok = $obj->close;
$ok = close(TIEDFH);
The close method is like a call to the shutdown method
followed by a call to the stopio method. It is the standard
way to close down an object.
Usage:
$obj->condition;
(Re-)establishes the condition of the associated filehandle after
an open() or accept(). (In other words, the open and accept
methods call the condition method.)
Sets the socket to be autoflushed and marks it binmode().
This method attempts to set the socket blocking or non-blocking, depending on
the state of the object's blocking parameter. (It may update that parameter
if the socket's state cannot be made to match.)
No useful value is returned.
Usage:
$ok = $obj->connect;
Attempts to establish a connection for the object. [Note the special information for re-trying connects on non-blocking sockets, later in this section.]
First, if the
object is currently connected or has been connected since the
last time it was opened, its close method is called. Then, if
the object is not currently open, its open method is called.
If it's not open after that, undef is returned. If it is
open, and if either of its srcaddrlist or srcaddr
parameters are set to indicate that a bind() is desired, and it
is not currently bound, its bind method is called. If the
bind method is called and fails, undef is returned. (Most
of the foregoing is a no-op for simple clients, so don't panic.)
Next, if the dstaddrlist object parameter is set to an array
reference, a call to connect() is made for each element of the
list until it succeeds or the list is exhausted. If the
dstaddrlist parameter is not an array reference, a single
attempt is made to call connect() with the dstaddr object
parameter. If no connect() call succeeded, undef is returned.
Finally, a call is made to the object's getsockinfo method,
and then the value from a call to its isconnected method is
returned.
Each of the attempts with the connect() builtin is timed out separately.
If there is no timeout parameter for the object, and the socket is
blocking (which is the default), the timeout period is strictly at the
mercy of your operating system. If there is no timeout parameter and the
socket is non-blocking, that's effectively the same as having a timeout
parameter value of 0. If there is a timeout parameter, the socket
is made non-blocking temporarily (see param_saver below), and the
indicated timeout value will be used to limit the connection attempt. An
attempt is made to preserve any meaningful $! values when all connection
attempts have failed. In particular, if the timeout parameter is 0,
then each failed connect returns without completing the processing of
the dstaddrlist object parameter. This is so that the re-try logic
for connections in progress will be more useful.
If, on entry to the connect method, the object is already marked as
having a connection in progress ($obj->isconnecting returns true),
then the connection will be re-tried with a timeout of 0 to see whether it
has succeeded in the meanwhile. The appropriate success/fail condition
for that check will be returned, with no further processing of the
dstaddrlist object parameter.
Note that the derived classes tend to provide additional
capabilities which make the connect method easier to use than
the above description would indicate.
Usage:
$ok = $obj->delparam($keyname);
Sugar-coated call to the delparams method.
Usage:
$ok = $obj->delparams(\@keynames);
Removes the settings for the specified parameters. Uses the
setparams method (with undef for the values) to validate
that the removal is allowed by the owning object. If the
invocation of setparams is successful, then the parameters in
question are removed. Returns 1 if all the removals were
successful, and undef otherwise.
Usage:
$ok = $obj->didlisten;
Returns true if the object's listen method has been used
successfully, and the object is still bound. If this method has
not been overridden by a derived class, the value is undef on
failure and the $maxqueue value used for the listen() builtin
on success.
Usage:
$iseof = $obj->EOF();
$iseof = eof(TIEDFH);
Provided for tied filehandle support. Determines whether select()
says that a read would work immediately, and tries it if so.
If the read was tried and returned an eof condition, 1 is returned.
The return is 0 on read errors or when select() said that a read
would block. Note that this interferes with use of the select()
built-in, since it has to buffer the read data if the read was
successful.
Usage:
$rval = $obj->fcntl($func, $value);
Returns the result of an fcntl() call on the associated I/O stream.
Usage:
$data = $TIED_SCALAR;
This is for the support of the TIESCALAR interface. It returns
the result of a call to the READLINE method on the underlying object.
Usage:
$vecstring = $obj->fhvec;
Returns a vector suitable as an argument to the 4-argument select()
call. This is for use in doing selects with multiple I/O streams.
See also select.
Usage:
$fnum = $obj->fileno;
$fnum = fileno(TIEDFH);
Returns the actual file descriptor number for the underlying socket. See getfh for some restrictions as to the safety of using this.
Usage:
$string = $obj->format_addr($sockaddr);
$string = format_addr Module $sockaddr;
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.
Usage:
$string = $obj->format_local_addr;
Returns a formatted representation of the local socket address associated with the object.
Usage:
$string = $obj->format_remote_addr;
Returns a formatted representation of the remote socket address associated with the object.
This is just a sugar-coated way to call the recv method which will
work with indirect-object syntax. See recv for details.
Usage:
$char = $obj->GETC;
$char = getc(TIEDFH);
This method uses the recv method with a $flags argument of 0 and
a $maxlen argument of 1 to emulate the getc() builtin. Like that builtin,
it returns a string representing the character read when successful,
and undef on eof or errors. This method exists for the support of tied
filehandles. It's unreliable for non-blocking sockets.
Usage:
$fhandle = $obj->getfh;
I've strongly resisted giving people direct access to the filehandle
embedded in the object because of the problems of mixing stdio input
calls and traditional socket-level I/O. However, if you're sure you can
keep things straight, here are the rules under which it's safe to use the
embedded filehandle:
Don't use perl's own stdio calls. Stick to sysread() and recv().
Don't use the object's getline method, since that stores a read-ahead
buffer in the object which only the object's own get/recv and
getline methods know to return to you. (The object's select method
knows about the buffer enough to tell you that a read will succeed if
there's saved data, though.) Similarly, avoid the object's EOF method.
Please don't change the state of the socket behind my back. That
means no close(), shutdown(), connect(), bind(), or listen()
built-ins. Use the corresponding methods instead, or all bets
are off. Of course, if you're only using this module to get the
connect() or bind() processing, and you're going to discard the object
after you've done your I/O, then it's OK to use the built-ins for I/O.
Just don't expect my code to know what you did behind my back.
That $fh is a glob ref, by the way, but that doesn't matter for calling
the built-in I/O primitives.
Usage:
$line = $obj->getline;
This is a simulation of scalar(<$filehandle>) that doesn't let
stdio confuse the get/recv method. As such, its return value is
not necessarily a complete line when the socket is non-blocking.
Usage:
@lines = $obj->getlines;
This is a lot like @lines = <$filehandle>, except that it doesn't
let stdio confuse the get/recv method. It's unreliable on non-blocking
sockets. It will produce a fatal (but trappable) error if not called in
list context. (In other words, it uses the die() builtin when not called in
list context.)
Usage:
$value = $obj->getparam($key, $defval, $def_if_undef);
$value = $obj->getparam($key, $defval);
$value = $obj->getparam($key);
Returns the current setting for the named parameter (in the
current object), or the specified default value if the parameter
is not in the object's current parameter list. If the optional
$def_if_undef parameter is true, then undefined values will be
treated the same as non-existent keys, and thus will return the
supplied default value ($defval).
Usage:
%hash = $obj->getparams(\@keynames, $noundefs);
%hash = $obj->getparams(\@keynames);
$llen = $obj->getparams(\@keynames, $noundefs);
$llen = $obj->getparams(\@keynames);
Returns a hash as a list (not a reference) consisting of the key-value
pairs corresponding to the specified keyname list. Only those
keys which exist in the current parameter list of the object will
be returned. If the $noundefs parameter is present and true,
then existing keys with undefined values will be suppressed as with
non-existent keys. If called in scalar context, returns the
number of values which would have been returned in list context.
(This is twice the number of key-value pairs, in case that wasn't clear.)
Usage:
$optsetting = $obj->getropt($level, $option);
$optsetting = $obj->getropt($optname);
Returns the raw value from a call to the getsockopt() builtin.
If both the $level and $option arguments are given as
numbers, the getsockopt() call will be made even if the given
socket option is not registered with the object. Otherwise, the
return value for unregistered options will be undef with the
value of $! set as described below for the getsopt method.
Usage:
$line = $obj->gets;
This is a simulation of scalar(<$filehandle>) that doesn't let
stdio confuse the get/recv method. (The gets method is just
an alias for the getline method, for partial compatibility with
the POSIX module.) This method is deprecated. Use the getline method
by that name, instead. The gets method may disappear in a future release.
Usage:
($localsockaddr, $peersockaddr) = $obj->getsockinfo;
$peersockaddr = $obj->getsockinfo;
Attempts to determine connection parameters associated with the
object. If a getsockname() call on the associated filehandle
succeeds, the srcaddr object parameter is set to that returned
sockaddr. If a getpeername() call on the associated filehandle
succeeds, the dstaddr parameter is set to that returned
sockaddr. In scalar context, if both socket addresses were
found, the getpeername() value is returned, otherwise undef is
returned. In list context, the getsockname() and getpeername()
values are returned, unless both are undefined.
Derived classes normally override this method with one which provides friendlier return information appropriate to the derived class, and which establishes more of the object parameters.
Usage:
@optvals = $obj->getsopt($level, $option);
@optvals = $obj->getsopt($optname);
Returns the unpacked values from a call to the getsockopt()
builtin. In order to do the unpacking, the socket option must
have been registered with the object. See the additional discussion of
socket options in initsockopts below.
Since registered socket options are known by name as well as by
their level and option values, it is possible to make calls using
only the option name. If the name is not registered with the object,
the return value is the same as that for getsopt $obj -1,-1,
which is an empty return array and $! set appropriately (should
be EINVAL).
Examples:
($sotype) = $obj->getsopt('SO_TYPE');
@malinger = $obj->getsopt(SOL_SOCKET, SO_LINGER);
($sodebug) = $obj->getsopt('SOL_SOCKET', 'SO_DEBUG');
Usage:
return undef unless $self->init;
Verifies that all previous parameter assignments are valid (via
checkparams). Returns the incoming object on success, and
undef on failure. This method is normally called from the new
method appropriate to the class of the created object.
Usage:
$rval = $obj->ioctl($func, $value);
Returns the result of an ioctl() call on the associated I/O stream.
Usage:
$ok = $obj->isbound;
Returns true if the object's bind method has been used
successfully, and the binding is still in effect. If this method
has not been overridden by a derived class, the value is the
saved return value of the call to the bind() builtin (if it was
called).
Usage:
$ok = $obj->isconnected;
Returns true if the object's connect method has been used
successfully to establish a ``session'', and that session is still
connected. If this method has not been overridden by a derived
class, the value is the saved return value of the call to the
connect() builtin (if it was called).
Usage:
$ok = $obj->isconnecting;
Returns true if the object's connect method has been used
with a timeout or on a non-blocking socket, and the connect() did
not complete. In other words, the failure from the connect() builtin
indicated that the operation was still in progress. (A rejected
connection or a connection which exceeded the operating system's timeout
is said to have completed unsuccessfully, rather than not to have completed.)
Usage:
$ok = $obj->isopen;
Returns true if the object currently has a socket attached to its
associated filehandle, and false otherwise. If this method has
not been overridden by a derived class, the value is the saved
return value of the call to the socket() builtin (if it was
called).
Usage:
$ok = $obj->listen($maxqueue);
$ok = $obj->listen;
Makes a call to the listen() builtin on the filehandle associated
with the object. Propagates the return value from listen(). If
the $maxqueue parameter is missing, it defaults to the value
of the object's maxqueue parameter, or the value of SOMAXCONN.
If the SOMAXCONN constant is not available in your
configuration, the default value used for the listen method is
5. This method will fail if the object is not bound and cannot
be made bound by a simple call to its bind method.
Usage:
$obj = $classname->new();
$obj = $classname->new(\%parameters);
Returns a newly-initialised object of the given class. If called
for a class other than Net::Gen, 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 validation.)
Usage:
$obj = $classname->new_from_fh(*FH);
$obj = $classname->new_from_fh(\*FH);
$obj = $classname->new_from_fd(fileno($fh));
Returns a newly-initialised object of the given class, open on a
newly-dup()ed copy of the given filehandle or file descriptor.
As many of the standard object parameters as possible will be
determined from the passed filehandle. This is determined (in
part) by calling the corresponding new, init, and
getsockinfo methods for the new object.
Only real filehandles or file descriptor numbers are allowed as arguments. This method makes no attempt to resolve filehandle names. Yes, despite having two names, there's really just one method.
Usage:
$ok = $obj->open;
Makes a call to the socket() builtin, using the current object
parameters to determine the desired protocol family, socket type,
and protocol number. If the object was already open, its
stopio method will be called before socket() is called again.
The object parameters consulted (and possibly updated) are PF,
AF, proto, type, and blocking. Returns true if the socket() call
results in an open filehandle, undef otherwise.
Usage:
my $savedstuff = $obj->param_saver(@param_names);
my $savedstuff = $obj->paramSaver(@param_names);
Saves the values (or lack thereof) for the indicated parameter names
by wrapping them (and the original object)
in an object blessed into an alternate package. When this `saver' object
is destroyed (typically because the `my' variable went out of scope),
the previous values of the parameters for the original object will be
restored. This allows for temporary changes to an object's parameter
settings without the worry of whether an inopportune die() will prevent
the restoration of the original settings.
An example (from the connect method):
my $saveblocking = $self->param_saver('blocking');
(This is used when there is a timeout parameter for the object.)
See put for details, as this method is just an alias for the put method.
The PRINT alias is for the support of tied filehandles.
Usage:
$ok = $obj->PRINTF($format, @args);
$ok = printf TIEDFH $format, @args;
This method uses the sprintf() builtin and the PRINT method
to send the @args values to the
filehandle associated with the object, using the $format format string.
It exists for the support of tied filehandles.
Usage:
$ok = $obj->put(@whatever);
$ok = put $obj @whatever;
This method uses the print() builtin to send the @whatever
arguments to the filehandle associated with the object. That
filehandle is always marked for autoflushing by the open
method, so the method is in effect equivalent to this:
$ok = $obj->send(join($, , @whatever) . $\ , 0);
However, since multiple fwrite() calls are sometimes involved in
the actual use of print(), this method can be more efficient than
the above code sample for large strings in the argument list.
It's a bad idea except on stream sockets (SOCK_STREAM)
though, since the record boundaries are unpredictable through
stdio. It's also a bad idea on non-blocking sockets, since the amount
of data actually written to the socket is unknown.
This method makes no attempt to trap SIGPIPE.
Usage:
$numread = $obj->READ($buffer, $maxlen);
$numread = $obj->READ($buffer, $maxlen, $offset);
$numread = read(TIEDFH, $buffer, $maxlen);
$numread = read(TIEDFH, $buffer, $maxlen, $offset);
This method uses the recv method (with a flags argument of 0) to
emulate the read() and sysread() builtins. This is specifically for the
support of tied filehandles. Like the emulated builtins, this method
returns the number of bytes successfully read, or undef on error.
Usage:
$line = $obj->READLINE;
@lines = $obj->READLINE;
$line = readline(TIEDFH); # or $line = <TIEDFH>;
@lines = readline(TIEDFH); # or @lines = <TIEDFH>;
This method supports the use of the <> (or readline()) operator
on tied filehandles. In scalar context, it uses the getline method.
In list context, it reads all remaining input on the socket (until eof, which
makes this unsuitable for connectionless socket types such as UDP), and
splits it into lines based on the current value of the $/ variable.
The return value is unreliable for non-blocking sockets.
Usage:
$from = $obj->RECV($buffer, $maxlen, $flags);
$from = $obj->RECV($buffer, $maxlen);
$from = $obj->RECV($buffer);
This method calls the recv() method with the arguments and return
rearranged to match the recv() builtin. This is for the support of
tied filehandles.
Usage:
$record = $obj->recv($maxlen, $flags, $whence);
$record = $obj->recv($maxlen, $flags);
$record = $obj->recv($maxlen);
$record = $obj->recv;
This method calls the recv() builtin, and returns a buffer (if
one is received) or undef on eof or error. If an eof is seen
on the socket (as checked with its ckeof method), then $!
will be 0 on return. If the $whence argument is supplied, it
will be filled in with the sending socket address if possible.
If the $flags argument is not supplied, it defaults to 0. If
the $maxlen argument is not supplied, it is defaulted to the
receive buffer size of the associated filehandle (if known), or
the preferred blocksize of the associated filehandle (if known,
which it usually won't be), or 8192.
Usage:
($nfound, $timeleft, $rbool, $wbool, $xbool) =
$obj->select($doread, $dowrite, $doxcept, $timeout);
$nfound = $obj->select($doread, $dowrite, $doxcept, $timeout);
Issues a 4-argument select() call for the associated I/O stream. All
arguments are optional. The $timeout argument is the same as the fourth
argument to the select() builtin.
The first three are booleans, used to determine
whether the method should include the object's I/O stream in the
corresponding parameter to the select() call. The return in list context is
the standard two values from select(), follwed by booleans indicating
whether the actual select() call found reading, writing, or exception to be
true. In scalar context, the routine returns only the count of the number
of matching conditions. This is probably only useful when you're checking
just one of the three possible conditions.
Usage:
$ok = $obj->send($buffer, $flags, $destsockaddr);
$ok = $obj->send($buffer, $flags);
$ok = $obj->send($buffer);
This method calls the send() builtin (three- or four-argument
form). The $flags parameter is defaulted to 0 if not
supplied. If the $destsockaddr value is missing or undefined,
and the socket is connected ($obj->isconnected returns true), then
the three-argument form of the send() builtin will be used. Otherwise, the
$destsockaddr parameter will be defaulted from the last recv()
peer address for the same kind of message (depending on whether
MSG_OOB is set in the $flags parameter). A defined
$destsockaddr will result in a four-argument send() call. The
return value from the send() builtin is returned. This method
makes no attempt to trap SIGPIPE.
Usage:
$ok = $obj->sendto($buffer, $destsockaddr, $flags);
$ok = $obj->sendto($buffer, $destsockaddr);
This method calls the send() builtin (four-argument form). The
$flags parameter is defaulted to 0 if not supplied. The
return value from the send() builtin is returned. This method
makes no attempt to trap SIGPIPE.
Usage:
$ok = $obj->setparam($key, $value, $newonly, $checkup);
$ok = $obj->setparam($key, $value, $newonly);
$ok = $obj->setparam($key, $value);
Sets a single new parameter. Uses the setparams method, and
has the same rules for the handling of the $newonly and
$checkup parameters. Returns 1 if the set was successful, and
undef otherwise.
Usage:
$ok = $obj->setparams(\%newparams, $newonly, $checkup);
$ok = $obj->setparams(\%newparams, $newonly);
$ok = $obj->setparams(\%newparams);
Sets new parameters from the given hashref, with validation.
This is done in a loop over the key, value pairs from the
newparams parameter. The precise nature of the validation
depends on the $newonly and $checkup parameters (which are
optional), but in all cases the keys to be set are checked
against those registered with the object. If the $newonly
parameter is negative, the value from the hashref will only be
set if there is not already a defined value associated with that
key, but the skipping of the setting of the value is silent. If the
$newonly parameter is not negative or if there is no existing
defined value, if the $checkup parameter is false then the
setting of the new value is skipped if the new value is identical
to the old value. If those checks don't cause the setting of a
new value to be skipped, then if the $newonly parameter is
positive and there is already a defined value for the specified
key, a warning will be issued and the new value will not be set.
If none of the above checks cause the setting of a new value to be skipped, but if the specified key has a validation routine, that routine will be called with the given object, the current key, and the proposed new value as parameters. It is allowed for the validation routine to alter the new-value argument to change what will be set. (This is useful when changing a hostname to be in canonical form, for example.) If the validation routine returns a non-null string, that will be used to issue a warning, and the new value will not be set. If the validation routine returns a null string (or if there is no validation routine), the new value will (finally) get set for the given key.
The setparams method returns 1 if all parameters were
successfully set, and undef otherwise.
Usage:
$ok = $obj->setropt($level, $option, $rawvalue);
$ok = $obj->setropt($optname, $rawvalue);
Returns the result from a call to the setsockopt() builtin. If
the $level and $option arguments are both given as numbers, the
setsockopt() call will be made even if the option is not
registered with the object. Otherwise, unregistered options will
fail as for the setsopt method, below.
Usage:
$ok = $obj->setsopt($level, $option, @optvalues);
$ok = $obj->setsopt($optname, @optvalues);
Returns the result from a call to the setsockopt() builtin. In
order to be able to pack the @optvalues, the option must be
registered with the object, just as described in getsopt
above.
Usage:
$ok = $obj->shutdown($how);
$ok = $obj->shutdown;
Calls the shutdown() builtin on the filehandle associated with
the object. This method is a no-op, returning 1, if the
filehandle is not connected. The $how parameter is as per the
shutdown() builtin, which in turn should be as described in the
shutdown(2) manpage. If the $how parameter is not present,
it is assumed to be SHUT_RDWR (which is 2 on most UNIX systems).
Returns 1 if it has nothing to do, otherwise propagates the return from
the shutdown() builtin.
Usage:
$ok = $obj->stopio;
Calls the close() builtin on the filehandle associated with the
object, unless that filehandle is already closed. Returns 1 or
the return value from the close() builtin. This method is
primarily for the use of server modules which need to avoid
shutdown calls at inappropriate times. This method calls the
delparams method for the keys of srcaddr and dstaddr.
Usage:
$TIED_SCALAR = $data;
Provided for the support of tied scalars. Results in a call to the
put method, unless there's exactly one arg and it's undef.
In that case, since this normally results from undef $TIED_SCALAR,
it's ignored.
Usage:
tie *FH, $package, @options or die;
print FH $out_data;
print $in_data while defined($in_data = <FH>);
untie *FH;
Tieing of a filehandle to a network handle is supported by this base
However, this method only succeeds if the related call to the new
method returns an object for which the isconnected method returns
true. Thus, the most useful example is in
Net::UDP.
Usage:
tie $x, $package, @options or die;
$x = $out_data;
print $in_data while defined($in_data = $x);
untie $x;
Tieing of scalars to a network handle is supported by this base class.
However, this method only succeeds if the related call to the new
method returns an object for which the isconnected method returns
true. Thus, the useful examples are in
Net::TCP
and
Net::UDP.
Usage:
$obj->unbind;
Removes any saved binding for the object. Unless the object is
currently connected, this will result in a call to its close
method, in order to ensure that any previous binding is removed.
Even if the object is connected, the srcaddrlist object
parameter is removed (via the object's delparams method). The
return value from this method is indeterminate.
Usage:
$was = $obj->wasconnected;
Returns true if the object has had a successful connect() completion
since it was last opened. Returns false after a close() or on a new
object. Also returns true if $obj->isconnecting is true.
Usage:
$nwritten = $obj->WRITE($buf, $len);
$nwritten = $obj->WRITE($buf, $len, $offset);
$nwritten = syswrite(TIEDFH, $buf, $len);
$nwritten = syswrite(TIEDFH, $buf, $len, $offset);
This method exists for support of syswrite() on tied filehandles.
It calls the syswrite() builtin on the underlying filehandle with the
same parameters.
Yes, I know that Perl doesn't really have protected methods as such. However, these are the methods which are only useful for implementing derived classes, and not for the general user.
Usage:
$wasiteof = $obj->ckeof;
After a 0-length read in the get() routine, it calls this method to
determine whether such a 0-length read meant EOF. The default method
supplied here checks for non-blocking sockets (if necessary), and
for a SOCK_STREAM socket. If EOF_NONBLOCK is true, or if the
VAL_O_NONBLOCK flag was not set in the fcntl() flags for the
socket, or if the error code was not VAL_EAGAIN, and the socket
is of type SOCK_STREAM, then this method returns true. It
returns a false value otherwise. This method is overridable for
classes like Net::Dnet, which support SOCK_SEQPACKET and
need to make a protocol-family-specific check to tell a 0-length
packet from EOF.
Usage:
$classname->initsockopts($level, \%optiondesc);
Given a prototype optiondesc hash ref, updates it to include all the data needed for the values it can find, and deletes the ones it can't. For example, here's a single entry from such a prototype optiondesc:
'SO_LINGER' => ['II'],
Given that, and the $level of SOL_SOCKET, and the incoming
class name of Net::Gen, initsockopts will attempt to
evaluate SO_LINGER in package Net::Gen, and if it succeeds
it will fill out the rest of the information in the associated
array ref, and add another key to the hash ref for the value of
SO_LINGER (which is 128 on my system). If it can't evaluate
that psuedo-constant, it will simply delete that entry from the
referenced hash. Assuming a successful evaluation of this entry,
the resulting entries would look like this:
'SO_LINGER' => ['II', SO_LINGER+0, SOL_SOCKET+0, 2],
SO_LINGER+0 => ['II', SO_LINGER+0, SOL_SOCKET+0, 2],
(All right, so the expressions would be known values, but maybe you get the idea.)
A completed optiondesc hash is a set of key-value pairs where the value is an array ref with the following elements:
[pack template, option value, option level, pack array len]
Such a completed optiondesc is one of the required arguments to
the register_options method (see below).
Usage:
$obj->register_options($levelname, $level, \%optiondesc);
This method attaches the socket options specified by the given option descriptions hash ref and the given level (as text and as a number) to the object. The registered set of socket options is in fact a hashref of hashrefs, where the keys are the level names and level numbers, and the values are the optiondesc hash refs which get registered.
Example:
$self->register_options('SOL_SOCKET', SOL_SOCKET+0, \%sockopts);
Usage:
$obj->register_param_handlers(\@keynames, \@keyhandlers);
$obj->register_param_handlers(\%key_handler_pairs);
This method registers the referenced keynames (if they haven't
already been registered), and establishes the referenced
keyhandlers as validation routines for those keynames. Each
element of the keyhandlers array must be a code reference. When
the setparams method invokes the handler, it will be called
with three arguments: the target object, the keyname in question,
and the proposed new value (which may be undef, especially if
being called from the delparams method). See the other
discussion of validation routines in the setparams method
description, above.
Usage:
$obj->register_param_keys(\@keynames);
This method registers the referenced keynames as valid parameters
for setparams and the like for this object. The new
methods can store arbitrary parameter values, but the init
method will later ensure that all those keys eventually got
registered. This out-of-order setup is allowed because of
possible cross-dependencies between the various parameters, so
they have to be set before they can be validated (in some cases).
Usage:
$value = $obj->_accessor($what);
$oldvalue = $obj->_accessor($what, $newvalue);
This method implements the use of the known parameter keys as get/set methods. It's used by the customised AUTOLOAD to generate such accessor functions as they're referenced. See blocking above for an example.
These are the socket options known to the Net::Gen module
itself:
SO_ACCEPTCONN,
SO_BROADCAST,
SO_DEBUG,
SO_DONTROUTE,
SO_ERROR,
SO_EXPANDED_RIGHTS,
SO_FAMILY,
SO_KEEPALIVE,
SO_LINGER,
SO_OOBINLINE,
SO_PAIRABLE,
SO_RCVBUF,
SO_RCVLOWAT,
SO_RCVTIMEO,
SO_REUSEADDR,
SO_REUSEPORT,
SO_SNDBUF,
SO_SNDLOWAT,
SO_SNDTIMEO,
SO_STATE,
SO_TYPE,
SO_USELOOPBACK,
SO_XSE
These are the object parameters registered by the Net::Gen
module itself:
Address family (will default from PF, and vice versa).
Set to 0 when a socket has been marked as non-blocking, and to 1
otherwise. If it's undef, it'll be treated as though it were
set to 1. The use of anything which even looks like stdio
calls on non-blocking sockets as at your own risk. If you don't know
how to work with non-blocking sockets already, the results of trying
them may surprise you.
The result of getpeername(), or an ephemeral proposed connect() address.
A reference to an array of socket addresses to try for connect().
An override of the default maximum queue depth parameter for
listen(). This will be used if the $maxqueue argument to
listen() is not supplied.
This parameter is set true to keep the connect method from
really calling the connect() built-in if the socket has not
had an source address specified and it is not bound. This
is used by the
Net::UNIX
and
Net::UDP
modules to keep
from exercising a bug in some socket implementations with respect
to how datagram sockets are handled. (This was specifically done
in response to quirks of Solaris 2.5.1.) Instead, the connect
method simply sets the dstaddr object parameter, which the send
method will respect.
Protocol family for this object. Will default from AF, and vice versa.
The protocol to pass to the socket() call (often defaulted to 0).
A boolean, indicating whether the bind method should do a
setsockopt() call to set SO_REUSEADDR to 1.
A boolean, indicating whether the bind method should do a
setsockopt() call to set SO_REUSEPORT to 1.
The result of getsockname(), or an ephemeral proposed bind() address.
A reference to an array of socket addresses to try for bind().
The maximum time to wait for connect() or accept() attempts to succeed.
See the discussion of timeouts and non-blocking sockets
in connect above.
The socket type to create (SOCK_STREAM, SOCK_DGRAM, etc.)
Usage:
$connect_address = pack_sockaddr($family, $fam_addr);
Returns a packed struct sockaddr corresponding to the provided
$family (which must be a number) and the address-family-specific
$fam_addr (pre-packed).
Usage:
($family, $fam_addr) = unpack_sockaddr($packed_address);
The inverse of pack_sockaddr().
Various socket-related errno values. See :errnos for the list.
These routines will always be defined, but they will return 0 if the
corresponding error symbol was not found on your system.
Returns a boolean value depending on whether a read from a
non-blocking socket can distinguish an end-of-file condition from
a no-data-available condition. This corresponds to the value
available from the Config module as
$Config::Config{'d_eofnblk'}), except that EOF_NONBLOCK is
always defined.
Gives the integer return value found by the Configure script
for a read() system call on a non-blocking socket which has no
data available. This is similar to the string representation of
the value available from the Config module as
$Config::Config{'rd_nodata'}.
Gives the value of the error symbol found by the Configure
script which is set by a non-blocking filehandle when no data is
available. This differs from the value available from the
Config module ($Config::Config{'eagain'}) in that the
latter is a string, typically "EAGAIN".
Gives the value found by the Configure script for setting a
filehandle non-blocking. The value available from the Config
module is a string representing the value found
($Config::Config{'o_nonblock'}), whereas the value from
VAL_O_NONBLOCK is an integer, suitable for passing to
sysopen() or for eventual use in fcntl().
None.
AF_APPLETALK AF_CCITT AF_CHAOS AF_CTF AF_DATAKIT
AF_DECnet AF_DLI AF_ECMA AF_HYLINK AF_IMPLINK
AF_INET AF_ISO AF_LAST AF_LAT AF_LINK AF_LOCAL AF_NETMAN
AF_NS AF_OSI AF_PUP AF_ROUTE AF_SNA AF_UNIX
AF_UNSPEC AF_USER AF_WAN AF_X25 EADDRINUSE
EADDRNOTAVAIL EAFNOSUPPORT EAGAIN EALREADY EBADF
EBADMSG ECONNABORTED ECONNREFUSED ECONNRESET
EDESTADDRREQ EHOSTDOWN EHOSTUNREACH EINPROGRESS
EINVAL EISCONN EMSGSIZE ENETDOWN ENETRESET
ENETUNREACH ENOBUFS ENODATA ENOENT ENOPROTOOPT
ENOSR ENOSTR ENOTCONN ENOTSOCK EOF_NONBLOCK
EOPNOTSUPP EPFNOSUPPORT EPROTO EPROTONOSUPPORT
EPROTOTYPE ESHUTDOWN ESOCKTNOSUPPORT ETIME
ETIMEDOUT ETOOMANYREFS EWOULDBLOCK pack_sockaddr
PF_APPLETALK PF_CCITT PF_CHAOS PF_CTF PF_DATAKIT
PF_DECnet PF_DLI PF_ECMA PF_HYLINK PF_IMPLINK
PF_INET PF_ISO PF_LAST PF_LAT PF_LINK PF_LOCAL PF_NETMAN
PF_NS PF_OSI PF_PUP PF_ROUTE PF_SNA PF_UNIX
PF_UNSPEC PF_USER PF_WAN PF_X25 RD_NODATA
SHUT_RD SHUT_RDWR SHUT_WR SOCK_DGRAM SOCK_RAW
SOCK_RDM SOCK_SEQPACKET SOCK_STREAM SOL_SOCKET
SOMAXCONN SO_ACCEPTCONN SO_BROADCAST SO_DEBUG
SO_DONTROUTE SO_ERROR SO_EXPANDED_RIGHTS SO_FAMILY
SO_KEEPALIVE SO_LINGER SO_OOBINLINE SO_PAIRABLE
SO_RCVBUF SO_RCVLOWAT SO_RCVTIMEO SO_REUSEADDR
SO_REUSEPORT SO_SNDBUF SO_SNDLOWAT SO_SNDTIMEO
SO_STATE SO_TYPE SO_USELOOPBACK SO_XSE
unpack_sockaddr VAL_EAGAIN VAL_O_NONBLOCK
The following :tags are available for grouping exported items together:
AF_APPLETALK AF_CCITT AF_CHAOS AF_CTF AF_DATAKIT
AF_DECnet AF_DLI AF_ECMA AF_HYLINK AF_IMPLINK
AF_INET AF_ISO AF_LAST AF_LAT AF_LINK AF_LOCAL AF_NETMAN
AF_NS AF_OSI AF_PUP AF_ROUTE AF_SNA AF_UNIX
AF_UNSPEC AF_USER AF_WAN AF_X25
EADDRINUSE EADDRNOTAVAIL EAFNOSUPPORT EAGAIN
EALREADY EBADF EBADMSG ECONNABORTED ECONNREFUSED
ECONNRESET EDESTADDRREQ EHOSTDOWN EHOSTUNREACH
EINPROGRESS EINVAL EISCONN EMSGSIZE ENETDOWN ENETRESET
ENETUNREACH ENOBUFS ENODATA ENOENT ENOPROTOOPT ENOSR
ENOSTR ENOTCONN ENOTSOCK EOPNOTSUPP EPFNOSUPPORT
EPROTO EPROTONOSUPPORT EPROTOTYPE ESHUTDOWN
ESOCKTNOSUPPORT ETIME ETIMEDOUT ETOOMANYREFS EWOULDBLOCK
PF_APPLETALK PF_CCITT PF_CHAOS PF_CTF PF_DATAKIT
PF_DECnet PF_DLI PF_ECMA PF_HYLINK PF_IMPLINK
PF_INET PF_ISO PF_LAST PF_LAT PF_LINK PF_LOCAL PF_NETMAN
PF_NS PF_OSI PF_PUP PF_ROUTE PF_SNA PF_UNIX
PF_UNSPEC PF_USER PF_WAN PF_X25
SHUT_RD SHUT_WR SHUT_RDWR
SO_ACCEPTCONN SO_BROADCAST SO_DEBUG SO_DONTROUTE
SO_ERROR SO_EXPANDED_RIGHTS SO_FAMILY SO_KEEPALIVE
SO_LINGER SO_OOBINLINE SO_PAIRABLE SO_RCVBUF
SO_RCVLOWAT SO_RCVTIMEO SO_REUSEADDR SO_REUSEPORT
SO_SNDBUF SO_SNDLOWAT SO_SNDTIMEO SO_STATE SO_TYPE
SO_USELOOPBACK SO_XSE
SOL_SOCKET SOCK_STREAM SOCK_DGRAM SOCK_RAW
SOCK_RDM SOCK_SEQPACKET
All of the above.
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.) It also works with interpreter-based threads ('ithreads') in more recent perl releases.
Net::Inet(3), Net::UNIX(3), Net::Dnet(3)
Spider Boardman <spidb@cpan.org>