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".
- new
- Usage:
$obj = new Net::UNIX;
$obj = new Net::UNIX $pathname;
$obj = new Net::UNIX \%parameters;
$obj = new Net::UNIX $pathname, \%parameters;
$obj = 'Net::UNIX'->new();
$obj = 'Net::UNIX'->new($pathname);
$obj = 'Net::UNIX'->new(\%parameters);
$obj = 'Net::UNIX'->new($pathname, \%parameters);
Returns a newly-initialised object of the given class. If called for a
derived class, no validation of the supplied parameters will be performed.
(This is so that the derived class can add the parameter validation it
needs to the object before allowing the validation.) Otherwise, it will
cause the parameters to be validated by calling its "init"
method. In particular, this means that if a pathname is given, an object
will be returned only if a connect() call was successful.
The examples above show the indirect object syntax which many prefer, as
well as the guaranteed-to-be-safe static method call. There are occasional
problems with the indirect object syntax, which tend to be rather obscure
when encountered. See
http://www.xray.mpe.mpg.de/mailing-lists/perl5-porters/1998-01/msg01674.html
for details.
- init
- Usage:
return undef unless $self = $self->init;
return undef unless $self = $self->init(\%parameters);
return undef unless $self = $self->init($pathname);
return undef unless $self = $self->init($pathname, \%parameters);
Verifies that all previous parameter assignments are valid (via
"checkparams"). Returns the incoming object on success, and
"undef" on failure. Usually called only via a derived class's
"init" method or its own "new" call.
- bind
- Usage:
$ok = $obj->bind;
$ok = $obj->bind($pathname);
$ok = $obj->bind($pathname,\%newparameters);
Updates the object with the supplied new parameters (if supplied), then sets
up the "srcaddrlist" object parameter with the specified
$pathname argument (if supplied), and then returns the value from the
inherited "bind" method.
Example:
$ok = $obj->bind('/tmp/.fnord'); # start a service on /tmp/.fnord
- connect
- Usage:
$ok = $obj->connect;
$ok = $obj->connect($pathname);
$ok = $obj->connect($pathname,\%newparameters);
Attempts to establish a connection for the object. If the
"newparams" argument is specified, it will be used to update the
object parameters. Then, if the $pathname argument is specified, it will
be used to set the "dstaddrlist" object parameter. Finally, the
result of a call to the inherited "connect" method will be
returned.
- format_addr
- Usage:
$string = $obj->format_addr($sockaddr);
$string = format_addr Module $sockaddr;
Returns a formatted representation of the socket address. This is normally
just a pathname, or the constant string ''.
- PRINT
- Usage:
$ok = $obj->PRINT(@args);
$ok = print $tied_fh @args;
This method, intended to be used with tied filehandles, behaves like one of
two inherited methods from the "Net::Gen" class, depending on
the setting of the object parameter "unbuffered_output" and
whether the socket is a SOCK_STREAM (stream) socket or a datagram socket
(the default). If that parameter is false (the default) or the socket is a
stream socket, then the normal print() builtin is used. If the
"unbuffered_output" parameter is true for a datagram socket,
then each print() operation will actually result in a call to the
"send" method. The value of the $\ variable is ignored in that
case, but the $, variable is still used if the @args array has multiple
elements.
- READLINE
- Usage:
$line_or_datagram = $obj->READLINE;
$line_or_datagram = <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 Net::Gen 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"):
- unbuffered_input
- If true, the "READLINE" operation on tied filehandles which are
datagram sockets will return each recv() buffer as though it were a
single separate line, independently of the setting of the $/ variable. The
default is false, which causes the "READLINE" interface to
return lines split at boundaries as appropriate for $/. (The
"READLINE" method for tied filehandles is the
"<FH>" operation.)
- unbuffered_output
- If true, the "PRINT" operation on tied filehandles which are
datagram sockets will result in calls to the send() builtin rather
than the print() builtin, as described in "PRINT" above.
The default is false, which causes the "PRINT" method to use the
print() builtin.
- unbuffered_IO
- This object parameter's value is unreliable on "getparam" or
"getparams" method calls. It is provided as a handy way to set
both the "unbuffered_output" and "unbuffered_input"
object parameters to the same value at the same time during
"new" calls.
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.
- pack_sockaddr_un
- Usage:
$connect_address = pack_sockaddr_un($family, $pathname);
$connect_address = pack_sockaddr_un($pathname);
Returns the packed "struct sockaddr_un" corresponding to the
provided $family and $pathname arguments. The $family argument as assumed
to be "AF_UNIX" if it is missing. This is otherwise the same as
the pack_sockaddr_un() routine in the "Socket"
module.
- unpack_sockaddr_un
- Usage:
($family, $pathname) = unpack_sockaddr_un($connected_address);
$pathname = unpack_sockaddr_un($connected_address);
Returns the address family and pathname (if known) from the supplied packed
"struct sockaddr_un". This is the inverse of
pack_sockaddr_un(). It differs from the implementation in the
"Socket" module in its return of the $family value, and in that
it trims the returned pathname at the first null character.
- default
- None.
- exportable
- "pack_sockaddr_un" "unpack_sockaddr_un"
- tags
- The following :tags are available for grouping exportable
items:
- :routines
- "pack_sockaddr_un" "unpack_sockaddr_un"
- :ALL
- All of the above exportable items.
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>