NAME

Net::UNIX - UNIX-domain sockets interface module

SYNOPSIS

use Socket;			# optional
use Net::Gen;		# optional
use Net::UNIX;

DESCRIPTION

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.

Public Methods

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;

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.

Server::new

Usage:

$obj = new Net::UNIX::Server $pathname;
$obj = new Net::UNIX::Server $pathname, \%parameters;

Returns a newly-initialised object of the given class. This is much like the regular new method, except that it does a bind rather than a connect, and it does a listen.

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 ''.

Protected Methods

[See the description in "Protected Methods" in Net::Gen for my definition of protected methods in Perl.]

None.

Known Socket Options

There are no socket options known to the Net::UNIX module itself.

Known Object Parameters

There are no object parameters registered by the Net::UNIX module itself.

TIESCALAR

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 getline method (via the FETCH method).

Non-Method Subroutines

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.

Exports

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.

AUTHOR

Spider Boardman <spider@Orb.Nashua.NH.US>