lib::Net::Gen(3User Contributed Perl Documentatiolib::Net::Gen(3)NAMENet::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.
Also provided in this distribution are Net::Inet,
Net::TCP, Net::UDP, and Net::UNIX, 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_fh, init, checkparams, open, connect,
bind, listen
Parameter manipulation
setparams, setparam, delparams, delparam, getparams,
getparam
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,
TIEHANDLE
24/Aug/1997 perl 5.005, patch 03 1
lib::Net::Gen(3User Contributed Perl Documentatiolib::Net::Gen(3)
Tied scalar support
FETCH, STORE, TIESCALAR
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.
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 struct
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.
checkparams
Usage:
24/Aug/1997 perl 5.005, patch 03 2
lib::Net::Gen(3User Contributed Perl Documentatiolib::Net::Gen(3)
$ok = $obj->checkparams;
Verifies that all previous parameter assignments are
valid. (Normally called only via the init method,
rather than directly.)
close
Usage:
$ok = $obj->close;
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(). No useful value is returned.
connect
Usage:
$ok = $obj->connect;
Attempts to establish a connection for the object.
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.
24/Aug/1997 perl 5.005, patch 03 3
lib::Net::Gen(3User Contributed Perl Documentatiolib::Net::Gen(3)
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. Functions
just like it.
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.
fcntl
Usage:
$rval = $obj->fcntl($func, $value);
Returns the result of an fcntl() call on the
associated I/O stream.
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 the
24/Aug/1997 perl 5.005, patch 03 4
lib::Net::Gen(3User Contributed Perl Documentatiolib::Net::Gen(3)
select entry elsewhere in this document.
fileno
Usage:
$fnum = $obj->fileno;
Returns the actual file descriptor number for the
underlying socket. See the getfh entry elsewhere in
this documentfor 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 the recv entry elsewhere in this documentfor
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
24/Aug/1997 perl 5.005, patch 03 5
lib::Net::Gen(3User Contributed Perl Documentatiolib::Net::Gen(3)
successful, and undef on eof or errors. This method
exists for the support of tied filehandles.
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:
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.)
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.
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.
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
24/Aug/1997 perl 5.005, patch 03 6
lib::Net::Gen(3User Contributed Perl Documentatiolib::Net::Gen(3)
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);
Returns a hash (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 like non-existent keys.
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 objects 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.)
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
24/Aug/1997 perl 5.005, patch 03 7
lib::Net::Gen(3User Contributed Perl Documentatiolib::Net::Gen(3)
succeeds, the dstaddr parameter is set to that
returned sockaddr. In a scalar context, if both
socket addresses were found, the getpeername() value
is returned, otherwise undef is returned. In a list
context, the getsockname() and getpeername() values
are returned, unless both are undefined.
Derived classes normally replace 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 below in the initsockopts entry elsewhere in
this document.
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 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);
24/Aug/1997 perl 5.005, patch 03 8
lib::Net::Gen(3User Contributed Perl Documentatiolib::Net::Gen(3)
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).
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.
24/Aug/1997 perl 5.005, patch 03 9
lib::Net::Gen(3User Contributed Perl Documentatiolib::Net::Gen(3)
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_fh
Usage:
$obj = $classname->new_from_fh(*FH);
$obj = $classname->new_from_fh(\*FH);
$obj = $classname->new_from_fh(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.
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, and type. Returns true if the
socket() call results in an open filehandle, undef
otherwise.
PRINT
See the put entry elsewhere in this documentas this
method is just an alias for the pub method. The
PRINT alias is for the support of tied filehandles.
PRINTF
Usage:
24/Aug/1997 perl 5.005, patch 03 10
lib::Net::Gen(3User Contributed Perl Documentatiolib::Net::Gen(3)
$ok = $obj->PRINTF($format, @args);
$ok = printf TIEDFH $format, @args;
This method is exactly equivalent to
$obj->put(sprintf $format,@args). 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. 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 array
context, it reads all remaining input on the socket
24/Aug/1997 perl 5.005, patch 03 11
lib::Net::Gen(3User Contributed Perl Documentatiolib::Net::Gen(3)
(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.
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 (eventual) 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 select(). 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, returns only the count of the number
24/Aug/1997 perl 5.005, patch 03 12
lib::Net::Gen(3User Contributed Perl Documentatiolib::Net::Gen(3)
of matching conditions. This is probably only useful
when you're checking just one of the three possible
conditions.
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, the three- argument form of the
send() builtin will be used. 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.
send Usage:
$ok = $obj->send($buffer, $flags);
$ok = $obj->send($buffer);
This method calls the send() builtin (three-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.
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.
24/Aug/1997 perl 5.005, patch 03 13
lib::Net::Gen(3User Contributed Perl Documentatiolib::Net::Gen(3)
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
skipping 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
24/Aug/1997 perl 5.005, patch 03 14
lib::Net::Gen(3User Contributed Perl Documentatiolib::Net::Gen(3)
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 for the getsopt method, 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 2.
Returns 1 if 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.
unbind
Usage:
$obj->unbind;
Removes any saved binding for the object. Unless the
object is currently connected, this will result in a
24/Aug/1997 perl 5.005, patch 03 15
lib::Net::Gen(3User Contributed Perl Documentatiolib::Net::Gen(3)
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.
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
24/Aug/1997 perl 5.005, patch 03 16
lib::Net::Gen(3User Contributed Perl Documentatiolib::Net::Gen(3)
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 registerOptions method (see below).
registerOptions
register_options
Usage:
$obj->registerOptions($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->registerOptions('SOL_SOCKET', SOL_SOCKET+0, \%sockopts);
registerParamHandlers
register_param_handlers
Usage:
$obj->registerParamHandlers(\@keynames, \@keyhandlers);
$obj->registerParamHandlers(\%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
24/Aug/1997 perl 5.005, patch 03 17
lib::Net::Gen(3User Contributed Perl Documentatiolib::Net::Gen(3)
(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.
registerParamKeys
register_param_keys
Usage:
$obj->registerParamKeys(\@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).
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_KEEPALIVE, SO_OOBINLINE, SO_REUSEADDR,
SO_USELOOPBACK, SO_RCVBUF, SO_SNDBUF, SO_RCVTIMEO,
SO_SNDTIMEO, SO_RCVLOWAT, SO_SNDLOWAT, SO_TYPE,
SO_LINGER
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)
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.
24/Aug/1997 perl 5.005, patch 03 18
lib::Net::Gen(3User Contributed Perl Documentatiolib::Net::Gen(3)
PF Protocol family for this object
proto
The protocol to pass to the socket() call (often
defaulted to 0)
srcaddr
The result of getsockname(), or an ephemeral proposed
bind() address
srcaddrlist
A reference to an array of socket addresses to try
for bind()
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().
EOF_NONBLOCK
Returns a boolean value dependin 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
24/Aug/1997 perl 5.005, patch 03 19
lib::Net::Gen(3User Contributed Perl Documentatiolib::Net::Gen(3)
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
VAL_O_NONBLOCK VAL_EAGAIN RD_NODATA EOF_NONBLOCK
pack_sockaddr unpack_sockaddr
tags The following :tags are available for grouping
exported items together:
:NonBlockVals
EOF_NONBLOCK RD_NODATA VAL_EAGAIN VAL_O_NONBLOCK
:routines pack_sockaddr unpack_sockaddr
:ALL All of the above.
AUTHOR
Spider Boardman <spider@Orb.Nashua.NH.US>
24/Aug/1997 perl 5.005, patch 03 20
lib::Net::Gen(3User Contributed Perl Documentatiolib::Net::Gen(3)24/Aug/1997 perl 5.005, patch 03 21