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