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
7package IO::Socket::UNIX;
8
9use strict;
10use IO::Socket;
11use Carp;
12
13our @ISA = qw(IO::Socket);
14our $VERSION = "1.49";
15
16IO::Socket::UNIX->register_domain( AF_UNIX );
17
18sub new {
19    my $class = shift;
20    unshift(@_, "Peer") if @_ == 1;
21    return $class->SUPER::new(@_);
22}
23
24sub configure {
25    my($sock,$arg) = @_;
26    my($bport,$cport);
27
28    my $type = $arg->{Type} || SOCK_STREAM;
29
30    $sock->socket(AF_UNIX, $type, 0) or
31	return undef;
32
33    if(exists $arg->{Blocking}) {
34        $sock->blocking($arg->{Blocking}) or
35	    return undef;
36    }
37    if(exists $arg->{Local}) {
38	my $addr = sockaddr_un($arg->{Local});
39	$sock->bind($addr) or
40	    return undef;
41    }
42    if(exists $arg->{Listen} && $type != SOCK_DGRAM) {
43	$sock->listen($arg->{Listen} || 5) or
44	    return undef;
45    }
46    elsif(exists $arg->{Peer}) {
47	my $addr = sockaddr_un($arg->{Peer});
48	$sock->connect($addr) or
49	    return undef;
50    }
51
52    $sock;
53}
54
55sub hostpath {
56    @_ == 1 or croak 'usage: $sock->hostpath()';
57    my $n = $_[0]->sockname || return undef;
58    (sockaddr_un($n))[0];
59}
60
61sub peerpath {
62    @_ == 1 or croak 'usage: $sock->peerpath()';
63    my $n = $_[0]->peername || return undef;
64    (sockaddr_un($n))[0];
65}
66
671; # Keep require happy
68
69__END__
70
71=head1 NAME
72
73IO::Socket::UNIX - Object interface for AF_UNIX domain sockets
74
75=head1 SYNOPSIS
76
77    use IO::Socket::UNIX;
78
79    my $SOCK_PATH = "$ENV{HOME}/unix-domain-socket-test.sock";
80
81    # Server:
82    my $server = IO::Socket::UNIX->new(
83        Type => SOCK_STREAM(),
84        Local => $SOCK_PATH,
85        Listen => 1,
86    );
87
88    my $count = 1;
89    while (my $conn = $server->accept()) {
90        $conn->print("Hello " . ($count++) . "\n");
91    }
92
93    # Client:
94    my $client = IO::Socket::UNIX->new(
95        Type => SOCK_STREAM(),
96        Peer => $SOCK_PATH,
97    );
98
99    # Now read and write from $client
100
101=head1 DESCRIPTION
102
103C<IO::Socket::UNIX> provides an object interface to creating and using sockets
104in the AF_UNIX domain. It is built upon the L<IO::Socket> interface and
105inherits all the methods defined by L<IO::Socket>.
106
107=head1 CONSTRUCTOR
108
109=over 4
110
111=item new ( [ARGS] )
112
113Creates an C<IO::Socket::UNIX> object, which is a reference to a
114newly created symbol (see the C<Symbol> package). C<new>
115optionally takes arguments, these arguments are in key-value pairs.
116
117In addition to the key-value pairs accepted by L<IO::Socket>,
118C<IO::Socket::UNIX> provides.
119
120    Type    	Type of socket (eg SOCK_STREAM or SOCK_DGRAM)
121    Local   	Path to local fifo
122    Peer    	Path to peer fifo
123    Listen  	Queue size for listen
124
125If the constructor is only passed a single argument, it is assumed to
126be a C<Peer> specification.
127
128If the C<Listen> argument is given, but false, the queue size will be set to 5.
129
130If the constructor fails it will return C<undef> and set the
131C<$IO::Socket::errstr> package variable to contain an error message.
132
133    $sock = IO::Socket::UNIX->new(...)
134        or die "Cannot create socket - $IO::Socket::errstr\n";
135
136For legacy reasons the error message is also set into the global C<$@>
137variable, and you may still find older code which looks here instead.
138
139    $sock = IO::Socket::UNIX->new(...)
140        or die "Cannot create socket - $@\n";
141
142=back
143
144=head1 METHODS
145
146=over 4
147
148=item hostpath()
149
150Returns the pathname to the fifo at the local end
151
152=item peerpath()
153
154Returns the pathanme to the fifo at the peer end
155
156=back
157
158=head1 SEE ALSO
159
160L<Socket>, L<IO::Socket>
161
162=head1 AUTHOR
163
164Graham Barr. Currently maintained by the Perl Porters.  Please report all
165bugs at L<https://github.com/Perl/perl5/issues>.
166
167=head1 COPYRIGHT
168
169Copyright (c) 1996-8 Graham Barr <gbarr@pobox.com>. All rights reserved.
170This program is free software; you can redistribute it and/or
171modify it under the same terms as Perl itself.
172
173=cut
174