This is a live mirror of the Perl 5 development currently hosted at https://github.com/perl/perl5
small improvements to documentation of IO::Socket
[perl5.git] / dist / IO / lib / IO / Socket / UNIX.pm
1 # IO::Socket::UNIX.pm
2 #
3 # Copyright (c) 1997-8 Graham Barr <gbarr@pobox.com>. All rights reserved.
4 # This program is free software; you can redistribute it and/or
5 # modify it under the same terms as Perl itself.
6
7 package IO::Socket::UNIX;
8
9 use strict;
10 our(@ISA, $VERSION);
11 use IO::Socket;
12 use Carp;
13
14 @ISA = qw(IO::Socket);
15 $VERSION = "1.25";
16 $VERSION = eval $VERSION;
17
18 IO::Socket::UNIX->register_domain( AF_UNIX );
19
20 sub new {
21     my $class = shift;
22     unshift(@_, "Peer") if @_ == 1;
23     return $class->SUPER::new(@_);
24 }
25
26 sub configure {
27     my($sock,$arg) = @_;
28     my($bport,$cport);
29
30     my $type = $arg->{Type} || SOCK_STREAM;
31
32     $sock->socket(AF_UNIX, $type, 0) or
33         return undef;
34
35     if(exists $arg->{Local}) {
36         my $addr = sockaddr_un($arg->{Local});
37         $sock->bind($addr) or
38             return undef;
39     }
40     if(exists $arg->{Listen} && $type != SOCK_DGRAM) {
41         $sock->listen($arg->{Listen} || 5) or
42             return undef;
43     }
44     elsif(exists $arg->{Peer}) {
45         my $addr = sockaddr_un($arg->{Peer});
46         $sock->connect($addr) or
47             return undef;
48     }
49
50     $sock;
51 }
52
53 sub hostpath {
54     @_ == 1 or croak 'usage: $sock->hostpath()';
55     my $n = $_[0]->sockname || return undef;
56     (sockaddr_un($n))[0];
57 }
58
59 sub peerpath {
60     @_ == 1 or croak 'usage: $sock->peerpath()';
61     my $n = $_[0]->peername || return undef;
62     (sockaddr_un($n))[0];
63 }
64
65 1; # Keep require happy
66
67 __END__
68
69 =head1 NAME
70
71 IO::Socket::UNIX - Object interface for AF_UNIX domain sockets
72
73 =head1 SYNOPSIS
74
75     use IO::Socket::UNIX;
76
77 =head1 DESCRIPTION
78
79 C<IO::Socket::UNIX> provides an object interface to creating and using sockets
80 in the AF_UNIX domain. It is built upon the L<IO::Socket> interface and
81 inherits all the methods defined by L<IO::Socket>.
82
83 =head1 CONSTRUCTOR
84
85 =over 4
86
87 =item new ( [ARGS] )
88
89 Creates an C<IO::Socket::UNIX> object, which is a reference to a
90 newly created symbol (see the C<Symbol> package). C<new>
91 optionally takes arguments, these arguments are in key-value pairs.
92
93 In addition to the key-value pairs accepted by L<IO::Socket>,
94 C<IO::Socket::UNIX> provides.
95
96     Type        Type of socket (eg SOCK_STREAM or SOCK_DGRAM)
97     Local       Path to local fifo
98     Peer        Path to peer fifo
99     Listen      Queue size for listen
100
101 If the constructor is only passed a single argument, it is assumed to
102 be a C<Peer> specification.
103
104 If the C<Listen> argument is given, but false, the queue size will be set to 5.
105
106  NOTE NOTE NOTE NOTE NOTE NOTE NOTE NOTE NOTE NOTE NOTE NOTE
107
108 As of VERSION 1.18 all IO::Socket objects have autoflush turned on
109 by default. This was not the case with earlier releases.
110
111  NOTE NOTE NOTE NOTE NOTE NOTE NOTE NOTE NOTE NOTE NOTE NOTE
112
113 =back
114
115 =head1 METHODS
116
117 =over 4
118
119 =item hostpath()
120
121 Returns the pathname to the fifo at the local end
122
123 =item peerpath()
124
125 Returns the pathanme to the fifo at the peer end
126
127 =back
128
129 =head1 SEE ALSO
130
131 L<Socket>, L<IO::Socket>
132
133 =head1 AUTHOR
134
135 Graham Barr. Currently maintained by the Perl Porters.  Please report all
136 bugs to <perlbug@perl.org>.
137
138 =head1 COPYRIGHT
139
140 Copyright (c) 1996-8 Graham Barr <gbarr@pobox.com>. All rights reserved.
141 This program is free software; you can redistribute it and/or
142 modify it under the same terms as Perl itself.
143
144 =cut