On Apache
Under GNU General Public License
2012-05-24 20:41 @38.107.179.236 Crawled by CCBot/1.0 (+http://www.commoncrawl.org/bot.html)
Net::Gen(3pm) User Contributed Perl Documentation Net::Gen(3pm)
NAME
Net::Gen - generic sockets interface handling
SYNOPSIS
use Net::Gen;
DESCRIPTION
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".
Public Methods
The public methods are listed alphabetically below. Here is an indication of their
functional groupings:
Creation and setup
"new", "new_from_fd", "new_from_fh", "init", "checkparams", "open", "connect", "bind",
"listen"
Parameter manipulation
"setparams", "setparam", "delparams", "delparam", "getparams", "getparam",
"param_saver"
Low-level control
"unbind", "condition", "getsopt", "getropt", "setsopt", "setropt", "fcntl", "ioctl"
Medium-level control
"getsockinfo", "shutdown", "stopio", "close"
Informational
"isopen", "isconnected", "isbound", "didlisten", "fhvec", "getfh", "fileno"
I/O "send", "sendto", "put", "recv", "get", "getline", "gets", "select", "accept"
Utility routines
"format_addr", "format_local_addr", "format_remote_addr"
Tied filehandle support
"SEND", "PRINT", "PRINTF", "RECV", "READLINE", "READ", "GETC", "WRITE", "CLOSE",
"EOF", "BINMODE", "FILENO", "TIEHANDLE"
Tied scalar support
"FETCH", "STORE", "TIESCALAR"
Accessors
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:
accept
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.
bind
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.
BINMODE
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.
blocking
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.
checkparams
Usage:
$ok = $obj->checkparams;
Verifies that all previous parameter assignments are valid. (Normally called only via
the "init" method, rather than directly.)
close
CLOSE
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.
condition
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.
connect
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.
delparam
Usage:
$ok = $obj->delparam($keyname);
Sugar-coated call to the "delparams" method.
delparams
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.
didlisten
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.
EOF 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.
fcntl
Usage:
$rval = $obj->fcntl($func, $value);
Returns the result of an fcntl() call on the associated I/O stream.
FETCH
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.
fhvec
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".
fileno
FILENO
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.
format_addr
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.
format_local_addr
Usage:
$string = $obj->format_local_addr;
Returns a formatted representation of the local socket address associated with the
object.
format_remote_addr
Usage:
$string = $obj->format_remote_addr;
Returns a formatted representation of the remote socket address associated with the
object.
get This is just a sugar-coated way to call the "recv" method which will work with
indirect-object syntax. See "recv" for details.
GETC
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.
getfh
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:
o Don't use perl's own "stdio" calls. Stick to sysread() and recv().
o 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.
o 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.
getline
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.
getlines
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.)
getparam
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).
getparams
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.)
getropt
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.
gets
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.
getsockinfo
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.
getsopt
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');
init
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.
ioctl
Usage:
$rval = $obj->ioctl($func, $value);
Returns the result of an ioctl() call on the associated I/O stream.
isbound
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).
isconnected
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).
isconnecting
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.)
isopen
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).
listen
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.
new 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.)
new_from_fd
new_from_fh
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.
open
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.
param_saver
paramSaver
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.)
print
PRINT
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.
PRINTF
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.
put 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".
READ
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.
READLINE
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.
RECV
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.
recv
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.
select
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.
SEND
send
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".
sendto
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".
setparam
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.
setparams
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.
setropt
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.
setsopt
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.
shutdown
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.
stopio
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".
STORE
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.
TIEHANDLE
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".
TIESCALAR
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".
unbind
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.
wasconnected
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.
WRITE
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.
Protected Methods
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.
ckeof
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.
initsockopts
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).
register_options
registerOptions
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);
register_param_handlers
registerParamHandlers
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.
register_param_keys
registerParamKeys
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).
_accessor
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.
Known Socket Options
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"
Known Object Parameters
These are the object parameters registered by the "Net::Gen" module itself:
AF Address family (will default from PF, and vice versa).
blocking
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.
dstaddr
The result of getpeername(), or an ephemeral proposed connect() address.
dstaddrlist
A reference to an array of socket addresses to try for connect().
maxqueue
An override of the default maximum queue depth parameter for listen(). This will be
used if the $maxqueue argument to listen() is not supplied.
netgen_fakeconnect
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.
PF Protocol family for this object. Will default from AF, and vice versa.
proto
The protocol to pass to the socket() call (often defaulted to 0).
reuseaddr
A boolean, indicating whether the "bind" method should do a setsockopt() call to set
"SO_REUSEADDR" to 1.
reuseport
A boolean, indicating whether the "bind" method should do a setsockopt() call to set
"SO_REUSEPORT" to 1.
srcaddr
The result of getsockname(), or an ephemeral proposed bind() address.
srcaddrlist
A reference to an array of socket addresses to try for bind().
timeout
The maximum time to wait for connect() or accept() attempts to succeed. See the
discussion of timeouts and non-blocking sockets in "connect" above.
type
The socket type to create ("SOCK_STREAM", "SOCK_DGRAM", etc.)
Non-Method Subroutines
pack_sockaddr
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).
unpack_sockaddr
Usage:
($family, $fam_addr) = unpack_sockaddr($packed_address);
The inverse of pack_sockaddr().
E* 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.
EOF_NONBLOCK
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.
RD_NODATA
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'}.
VAL_EAGAIN
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".
VAL_O_NONBLOCK
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().
Exports
default
None.
exportable
"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"
tags
The following :tags are available for grouping exported items together:
:af "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"
:errnos
"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"
:families
The union of the ":af" and ":pf" tags.
:NonBlockVals
:non_block_vals
"EOF_NONBLOCK" "RD_NODATA" "VAL_EAGAIN" "VAL_O_NONBLOCK"
:pf "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"
:routines
"pack_sockaddr" "unpack_sockaddr"
:shutflags
"SHUT_RD" "SHUT_WR" "SHUT_RDWR"
:sockopts
"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"
:sockvals
"SOL_SOCKET" "SOCK_STREAM" "SOCK_DGRAM" "SOCK_RAW" "SOCK_RDM" "SOCK_SEQPACKET"
:ALL All of the above.
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.) It also works
with interpreter-based threads ('ithreads') in more recent perl releases.
SEE ALSO
Net::Inet(3), Net::UNIX(3), Net::Dnet(3)
AUTHOR
Spider Boardman <spidb AT cpan.org>
perl v5.10.0 2009-03-05 Net::Gen(3pm)
Generated by $Id: phpMan.php,v 4.49 2006/02/26 13:18:18 chedong Exp $ Author: Che Dong
On Apache
Under GNU General Public License
2012-05-24 20:41 @38.107.179.236 Crawled by CCBot/1.0 (+http://www.commoncrawl.org/bot.html)