|
|
Net::UNIX - UNIX-domain sockets interface module
use Net::Gen; # optional
use Net::UNIX;
The Net::UNIX module provides services for UNIX-domain socket
communication. It is layered atop the
Net::Gen
module, which
is part of the same distribution.
The following methods are provided by the Net::UNIX module
itself, rather than just being inherited from
Net::Gen.
Usage:
$obj = new Net::UNIX;
$obj = new Net::UNIX $pathname;
$obj = new Net::UNIX \%parameters;
$obj = new Net::UNIX $pathname, \%parameters;
$obj = 'Net::UNIX'->new();
$obj = 'Net::UNIX'->new($pathname);
$obj = 'Net::UNIX'->new(\%parameters);
$obj = 'Net::UNIX'->new($pathname, \%parameters);
Returns a newly-initialised object of the given class. If called
for a derived class, no validation of the supplied parameters
will be performed. (This is so that the derived class can add
the parameter validation it needs to the object before allowing
the validation.) Otherwise, it will cause the parameters to be
validated by calling its init method. In particular, this
means that if a pathname is given, an object will be returned
only if a connect() call was successful.
The examples above show the indirect object syntax which many prefer, as well as the guaranteed-to-be-safe static method call. There are occasional problems with the indirect object syntax, which tend to be rather obscure when encountered. See http://www.xray.mpe.mpg.de/mailing-lists/perl5-porters/1998-01/msg01674.html for details.
Usage:
return undef unless $self = $self->init;
return undef unless $self = $self->init(\%parameters);
return undef unless $self = $self->init($pathname);
return undef unless $self = $self->init($pathname, \%parameters);
Verifies that all previous parameter assignments are valid (via
checkparams). Returns the incoming object on success, and
undef on failure. Usually called only via a derived class's
init method or its own new call.
Usage:
$ok = $obj->bind;
$ok = $obj->bind($pathname);
$ok = $obj->bind($pathname,\%newparameters);
Updates the object with the supplied new parameters (if
supplied), then sets up the srcaddrlist object parameter with
the specified $pathname argument (if supplied), and then returns
the value from the inherited bind method.
Example:
$ok = $obj->bind('/tmp/.fnord'); # start a service on /tmp/.fnord
Usage:
$ok = $obj->connect;
$ok = $obj->connect($pathname);
$ok = $obj->connect($pathname,\%newparameters);
Attempts to establish a connection for the object. If the
newparams argument is specified, it will be used to update the
object parameters. Then, if the $pathname argument is specified,
it will be used to set the dstaddrlist object parameter.
Finally, the result of a call to the inherited connect method
will be returned.
Usage:
$string = $obj->format_addr($sockaddr);
$string = format_addr Module $sockaddr;
Returns a formatted representation of the socket address. This
is normally just a pathname, or the constant string ''.
Usage:
$ok = $obj->PRINT(@args);
$ok = print $tied_fh @args;
This method, intended to be used with tied filehandles, behaves like one
of two inherited methods from the
Net::Gen
class, depending on the
setting of the object parameter unbuffered_output and whether the
socket is a SOCK_STREAM (stream) socket or a datagram socket (the
default). If that parameter is false (the default) or the socket
is a stream socket, then the normal print() builtin is used.
If the unbuffered_output parameter is true for a datagram socket,
then each print()
operation will actually result in a call to the send method. The
value of the $\ variable is ignored in that case, but
the $, variable is still used if the @args array has multiple
elements.
Usage:
$line_or_datagram = $obj->READLINE;
$line_or_datagram = <TIED_FH>;
$line_or_datagram = readline(TIED_FH);
@lines_or_datagrams = $obj->READLINE;
@lines_or_datagrams = <TIED_FH>;
@lines_or_datagrams = readline(TIED_FH);
This method, intended to be used with tied filehandles, behaves
like one of two inherited methods from the Net::Gen class,
depending on the setting of the object parameter
unbuffered_input and whether the socket is a SOCK_STREAM (stream) socket
or a datagram socket (the default). If that parameter is false (the default)
or the socket is a stream socket,
then this method does line-buffering of its input as defined by
the current setting of the $/ variable. If the
unbuffered_input parameter is true for a datagram socket,
then the input records will
be exact recv() datagrams, disregarding the setting of the $/
variable.
[See the description in Protected Methods in the Net::Gen manpage for my definition of protected methods in Perl.]
None.
There are no socket options known to the Net::UNIX module itself.
The following object parameters are registered by the Net::UNIX module
(as distinct from being inherited from
Net::Gen):
If true, the READLINE operation on tied filehandles which
are datagram sockets will return each recv()
buffer as though it were a single separate line, independently of the setting
of the $/ variable. The default is false, which causes the READLINE
interface to return lines split at boundaries as appropriate for $/.
(The READLINE method for tied filehandles is the <FH>
operation.)
If true, the PRINT operation on tied filehandles which
are datagram sockets will result in calls to
the send() builtin rather than the print() builtin, as described in PRINT
above. The default is false, which causes the PRINT method to use the
print() builtin.
This object parameter's value is unreliable on getparam or getparams
method calls. It is provided as a handy way to set both the
unbuffered_output and unbuffered_input object parameters to the same
value at the same time during new calls.
Tieing of scalars to a UNIX-domain handle is supported by
inheritance from the TIESCALAR method of
Net::Gen. That
method only succeeds if a call to a new method results in an
object for which the isconnected method returns a true result.
Thus, for Net::UNIX, TIESCALAR will not succeed unless the
pathname argument is given.
Each assignment to the tied scalar is really a call to the put
method (via the STORE method), and each read from the tied
scalar is really a call to the READLINE method (via the
FETCH method).
As inherited from
Net::Gen, with the addition of
unbuffered datagram I/O options for the FETCH, READLINE,
and PRINT methods.
Usage:
$connect_address = pack_sockaddr_un($family, $pathname);
$connect_address = pack_sockaddr_un($pathname);
Returns the packed struct sockaddr_un corresponding to the
provided $family and $pathname arguments. The $family argument
as assumed to be AF_UNIX if it is missing. This is otherwise
the same as the pack_sockaddr_un() routine in the Socket
module.
Usage:
($family, $pathname) = unpack_sockaddr_un($connected_address);
$pathname = unpack_sockaddr_un($connected_address);
Returns the address family and pathname (if known) from the
supplied packed struct sockaddr_un. This is the inverse of
pack_sockaddr_un(). It differs from the implementation in the
Socket module in its return of the $family value, and in
that it trims the returned pathname at the first null character.
None.
The following :tags are available for grouping exportable items:
All of the above exportable items.
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::Gen(3), Net::UNIX::Server(3)
Spider Boardman <spidb@cpan.org>