Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages

  
 
  

home | help
Net::UNIX(3)	      User Contributed Perl Documentation	  Net::UNIX(3)

NAME
       Net::UNIX - UNIX-domain sockets interface module

SYNOPSIS
	   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;
	       $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.

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

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

   TIEHANDLE support
       As inherited from "Net::Gen", with the addition of unbuffered datagram
       I/O options for the "FETCH", "READLINE",	and "PRINT" methods.

   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.

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::Gen(3), Net::UNIX::Server(3)

AUTHOR
       Spider Boardman <spidb@cpan.org>

perl v5.24.1			  2017-07-02			  Net::UNIX(3)

NAME | SYNOPSIS | DESCRIPTION | THREADING STATUS | SEE ALSO | AUTHOR

Want to link to this manual page? Use this URL:
<https://www.freebsd.org/cgi/man.cgi?query=Net::UNIX&sektion=3&manpath=FreeBSD+12.1-RELEASE+and+Ports>

home | help