1# Copyright 1997,2002 Spider Boardman.
2# All rights reserved.
3#
4# Automatic licensing for this software is available.  This software
5# can be copied and used under the terms of the GNU Public License,
6# version 1 or (at your option) any later version, or under the
7# terms of the Artistic license.  Both of these can be found with
8# the Perl distribution, which this software is intended to augment.
9#
10# THIS PACKAGE IS PROVIDED "AS IS" AND WITHOUT ANY EXPRESS OR
11# IMPLIED WARRANTIES, INCLUDING, WITHOUT LIMITATION, THE IMPLIED
12# WARRANTIES OF MERCHANTIBILITY AND FITNESS FOR A PARTICULAR PURPOSE.
13
14# rcsid: "@(#) $Id: Server.dat,v 1.16 2002/03/30 10:11:24 spider Exp $"
15
16package Net::UNIX::Server;
17use 5.004_04;
18
19use strict;
20#use Carp;
21sub carp { require Carp; goto &Carp::carp; }
22sub croak { require Carp; goto &Carp::croak; }
23use vars qw($VERSION @ISA @EXPORT @EXPORT_OK %EXPORT_TAGS);
24
25BEGIN {
26    $VERSION = '1.0';
27    eval "sub Version { __PACKAGE__ . ' v$VERSION' }";
28}
29
30#use AutoLoader;		# someday add back, along with AUTOLOAD, below
31#use Exporter ();
32use Net::UNIX 1.0;
33use Net::Gen 1.0 qw(/^SOCK_/);
34
35BEGIN {
36    @ISA = 'Net::UNIX';
37
38# Items to export into callers namespace by default.
39# (Move infrequently used names to @EXPORT_OK below.)
40
41    @EXPORT = qw(
42    );
43
44    @EXPORT_OK = qw(
45    );
46
47    %EXPORT_TAGS = (
48	ALL		=> [@EXPORT, @EXPORT_OK],
49    );
50#    *AUTOLOAD = \$Net::Gen::AUTOLOAD;
51}
52
53# sub AUTOLOAD inherited from Net::Gen
54
55# since 5.003_96 will break simple subroutines with inherited autoload, cheat
56#sub AUTOLOAD
57#{
58#    #$Net::Gen::AUTOLOAD = $AUTOLOAD;
59#    goto &Net::Gen::AUTOLOAD;
60#}
61
62
63# Preloaded methods go here.  Autoload methods go after __END__, and are
64# processed by the autosplit program.
65
66# Can't autoload new & init when Net::Gen has them non-autoloaded.  Feh.
67
68# No additional sockopts for UNIX-domain sockets (?)
69
70sub new : locked
71{
72    my $whoami = $_[0]->_trace(\@_,1);
73    my($class,@Args,$self) = @_;
74    $self = $class->SUPER::new(@Args);
75    $class = ref $class if ref $class;
76    ($self || $class)->_trace(\@_,2," self" .
77			      (defined $self ? "=$self" : " undefined") .
78			      " after sub-new");
79    if ($self) {
80	$self->setparams({reuseaddr => 1}, -1);
81	if ($class eq __PACKAGE__) {
82	    unless ($self->init(@Args)) {
83		local $!;	# preserve errno
84		undef $self;	# against the side-effects of this
85		undef $self;	# another statement needed for unwinding
86	    }
87	}
88    }
89    ($self || $class)->_trace(0,1," returning " .
90			      (defined $self ? "self=$self" : "undefined"));
91    $self;
92}
93
94#& init($self [, $thispath][, \%params]) : {$self | undef}
95sub init
96{
97    my ($self,@args) = @_;
98    return undef unless $self->_init('thispath',@args);
99    if ($self->isbound) {
100	return undef
101	    unless $self->getparam('type') == SOCK_DGRAM or
102		$self->isconnected or $self->didlisten or $self->listen;
103    }
104    $self;
105}
106
1071;
108
109# autoloaded methods go after the END token (& pod) below
110
111__END__
112
113=head1 NAME
114
115Net::UNIX::Server - UNIX-domain sockets interface module for listeners
116
117=head1 SYNOPSIS
118
119    use Net::Gen;		# optional
120    use Net::UNIX;		# optional
121    use Net::UNIX::Server;
122
123=head1 DESCRIPTION
124
125The C<Net::UNIX::Server> module provides additional
126services for UNIX-domain socket
127communication.  It is layered atop the
128L<C<Net::UNIX>|Net::UNIX>
129and
130L<C<Net::Gen>|Net::Gen>
131modules,
132which are part of the same distribution.
133
134=head2 Public Methods
135
136The following methods are provided by the C<Net::UNIX::Server> module
137itself, rather than just being inherited from
138L<C<Net::UNIX>|Net::UNIX>
139or
140L<C<Net::Gen>|Net::Gen>.
141
142=over 4
143
144=item new
145
146Usage:
147
148    $obj = new Net::UNIX::Server;
149    $obj = new Net::UNIX::Server $pathname;
150    $obj = new Net::UNIX::Server $pathname, \%parameters;
151    $obj = 'Net::UNIX::Server'->new();
152    $obj = 'Net::UNIX::Server'->new($pathname);
153    $obj = 'Net::UNIX::Server'->new($pathname, \%parameters);
154
155Returns a newly-initialised object of the given class.  This is
156much like the regular C<new> methods of other modules in this
157distribution, except that it does a
158C<bind> rather than a C<connect>, and it does a C<listen>.  Unless
159specified otherwise with a C<type> object parameter, the underlying
160socket will be a datagram socket (C<SOCK_DGRAM>).
161
162The examples above show the indirect object syntax which many prefer,
163as well as the guaranteed-to-be-safe static method call.  There
164are occasional problems with the indirect object syntax, which
165tend to be rather obscure when encountered.  See
166http://www.xray.mpe.mpg.de/mailing-lists/perl5-porters/1998-01/msg01674.html
167for details.
168
169See L<Net::TCP::Server> for an example of running a server.  The
170differences are only in the module names and the fact that UNIX-domain
171sockets bind to a pathname rather than to a port number.  Of course,
172that example is for stream (C<type = SOCK_STREAM>) sockets rather than
173for datagrams.  UNIX-domain datagram sockets don't need to do an
174accept() (and can't where I've tested this code), and can't answer back
175to their clients unless those clients have also bound to a specific path
176name.
177
178=item init
179
180Usage:
181
182    return undef unless $self = $self->init;
183    return undef unless $self = $self->init(\%parameters);
184    return undef unless $self = $self->init($pathname);
185    return undef unless $self = $self->init($pathname, \%parameters);
186
187Verifies that all previous parameter assignments are valid (via
188C<checkparams>).  Returns the incoming object on success, and
189C<undef> on failure.  Usually called only via a derived class's
190C<init> method or its own C<new> call.
191
192=back
193
194=head2 Protected Methods
195
196[See the description in L<Net::Gen/"Protected Methods"> for my
197definition of protected methods in Perl.]
198
199None.
200
201=head2 Known Socket Options
202
203There are no socket options known to the C<Net::UNIX::Server> module itself.
204
205=head2 Known Object Parameters
206
207There are no object parameters registered by the C<Net::UNIX::Server> module
208itself.
209
210=head2 Exports
211
212=over 4
213
214=item default
215
216None.
217
218=item exportable
219
220None.
221
222=item tags
223
224The following I<:tags> are available for grouping exportable items:
225
226=over 6
227
228=item :ALL
229
230All of the above exportable items.
231
232=back
233
234Z<>
235
236=back
237
238=head1 THREADING STATUS
239
240This module has been tested with threaded perls, and should be as thread-safe
241as perl itself.  (As of 5.005_03 and 5.005_57, that's not all that safe
242just yet.)  It also works with interpreter-based threads ('ithreads') in
243more recent perl releases.
244
245=head1 SEE ALSO
246
247L<Net::UNIX(3)|Net::UNIX>,
248L<Net::Gen(3)|Net::Gen>
249
250=head1 AUTHOR
251
252Spider Boardman E<lt>spidb@cpan.orgE<gt>
253
254=cut
255
256#other sections should be added, sigh.
257
258#any real autoloaded methods go after this line
259