This is a live mirror of the Perl 5 development currently hosted at https://github.com/perl/perl5
9872d035263f6ca079b7e0c66030694ab372fed3
[perl5.git] / ext / Socket / Socket.pm
1 package Socket;
2
3 use vars qw($VERSION @ISA @EXPORT);
4 $VERSION = "1.5";
5
6 =head1 NAME
7
8 Socket, sockaddr_in, sockaddr_un, inet_aton, inet_ntoa - load the C socket.h defines and structure manipulators 
9
10 =head1 SYNOPSIS
11
12     use Socket;
13
14     $proto = getprotobyname('udp');
15     socket(Socket_Handle, PF_INET, SOCK_DGRAM, $proto);
16     $iaddr = gethostbyname('hishost.com');
17     $port = getservbyname('time', 'udp');
18     $sin = sockaddr_in($port, $iaddr);
19     send(Socket_Handle, 0, 0, $sin);
20
21     $proto = getprotobyname('tcp');
22     socket(Socket_Handle, PF_INET, SOCK_STREAM, $proto);
23     $port = getservbyname('smtp');
24     $sin = sockaddr_in($port,inet_aton("127.1"));
25     $sin = sockaddr_in(7,inet_aton("localhost"));
26     $sin = sockaddr_in(7,INADDR_LOOPBACK);
27     connect(Socket_Handle,$sin);
28
29     ($port, $iaddr) = sockaddr_in(getpeername(Socket_Handle));
30     $peer_host = gethostbyaddr($iaddr, AF_INET);
31     $peer_addr = inet_ntoa($iaddr);
32
33     $proto = getprotobyname('tcp');
34     socket(Socket_Handle, PF_UNIX, SOCK_STREAM, $proto);
35     unlink('/tmp/usock');
36     $sun = sockaddr_un('/tmp/usock');
37     connect(Socket_Handle,$sun);
38
39 =head1 DESCRIPTION
40
41 This module is just a translation of the C F<socket.h> file.
42 Unlike the old mechanism of requiring a translated F<socket.ph>
43 file, this uses the B<h2xs> program (see the Perl source distribution)
44 and your native C compiler.  This means that it has a 
45 far more likely chance of getting the numbers right.  This includes
46 all of the commonly used pound-defines like AF_INET, SOCK_STREAM, etc.
47
48 In addition, some structure manipulation functions are available:
49
50 =item inet_aton HOSTNAME
51
52 Takes a string giving the name of a host, and translates that
53 to the 4-byte string (structure). Takes arguments of both
54 the 'rtfm.mit.edu' type and '18.181.0.24'. If the host name
55 cannot be resolved, returns undef.
56
57 =item inet_ntoa IP_ADDRESS
58
59 Takes a four byte ip address (as returned by inet_aton())
60 and translates it into a string of the form 'd.d.d.d'
61 where the 'd's are numbers less than 256 (the normal
62 readable four dotted number notation for internet addresses).
63
64 =item INADDR_ANY
65
66 Note: does not return a number, but a packed string.
67
68 Returns the 4-byte wildcard ip address which specifies any
69 of the hosts ip addresses. (A particular machine can have
70 more than one ip address, each address corresponding to
71 a particular network interface. This wildcard address
72 allows you to bind to all of them simultaneously.)
73 Normally equivalent to inet_aton('0.0.0.0').
74
75 =item INADDR_LOOPBACK
76
77 Note - does not return a number.
78
79 Returns the 4-byte loopback address. Normally equivalent
80 to inet_aton('localhost').
81
82 =item INADDR_NONE
83
84 Note - does not return a number.
85
86 Returns the 4-byte invalid ip address. Normally equivalent
87 to inet_aton('255.255.255.255').
88
89 =item sockaddr_in PORT, ADDRESS
90
91 =item sockaddr_in SOCKADDR_IN
92
93 In an array context, unpacks its SOCKADDR_IN argument and returns an array
94 consisting of (PORT, ADDRESS).  In a scalar context, packs its (PORT,
95 ADDRESS) arguments as a SOCKADDR_IN and returns it.  If this is confusing,
96 use pack_sockaddr_in() and unpack_sockaddr_in() explicitly.
97
98 =item pack_sockaddr_in PORT, IP_ADDRESS
99
100 Takes two arguments, a port number and a 4 byte IP_ADDRESS (as returned by
101 inet_aton()). Returns the sockaddr_in structure with those arguments
102 packed in with AF_INET filled in.  For internet domain sockets, this
103 structure is normally what you need for the arguments in bind(),
104 connect(), and send(), and is also returned by getpeername(),
105 getsockname() and recv().
106
107 =item unpack_sockaddr_in SOCKADDR_IN
108
109 Takes a sockaddr_in structure (as returned by pack_sockaddr_in()) and
110 returns an array of two elements: the port and the 4-byte ip-address.
111 Will croak if the structure does not have AF_INET in the right place.
112
113 =item sockaddr_un PATHNAME
114
115 =item sockaddr_un SOCKADDR_UN
116
117 In an array context, unpacks its SOCKADDR_UN argument and returns an array
118 consisting of (PATHNAME).  In a scalar context, packs its PATHNAME
119 arguments as a SOCKADDR_UN and returns it.  If this is confusing, use
120 pack_sockaddr_un() and unpack_sockaddr_un() explicitly.
121 These are only supported if your system has E<lt>F<sys/un.h>E<gt>.
122
123 =item pack_sockaddr_un PATH
124
125 Takes one argument, a pathname. Returns the sockaddr_un structure with
126 that path packed in with AF_UNIX filled in. For unix domain sockets, this
127 structure is normally what you need for the arguments in bind(),
128 connect(), and send(), and is also returned by getpeername(),
129 getsockname() and recv().
130
131 =item unpack_sockaddr_un SOCKADDR_UN
132
133 Takes a sockaddr_un structure (as returned by pack_sockaddr_un())
134 and returns the pathname.  Will croak if the structure does not
135 have AF_UNIX in the right place.
136
137 =cut
138
139 use Carp;
140
141 require Exporter;
142 require DynaLoader;
143 @ISA = qw(Exporter DynaLoader);
144 @EXPORT = qw(
145         inet_aton inet_ntoa pack_sockaddr_in unpack_sockaddr_in
146         pack_sockaddr_un unpack_sockaddr_un
147         sockaddr_in sockaddr_un
148         INADDR_ANY INADDR_LOOPBACK INADDR_NONE
149         AF_802
150         AF_APPLETALK
151         AF_CCITT
152         AF_CHAOS
153         AF_DATAKIT
154         AF_DECnet
155         AF_DLI
156         AF_ECMA
157         AF_GOSIP
158         AF_HYLINK
159         AF_IMPLINK
160         AF_INET
161         AF_LAT
162         AF_MAX
163         AF_NBS
164         AF_NIT
165         AF_NS
166         AF_OSI
167         AF_OSINET
168         AF_PUP
169         AF_SNA
170         AF_UNIX
171         AF_UNSPEC
172         AF_X25
173         MSG_DONTROUTE
174         MSG_MAXIOVLEN
175         MSG_OOB
176         MSG_PEEK
177         PF_802
178         PF_APPLETALK
179         PF_CCITT
180         PF_CHAOS
181         PF_DATAKIT
182         PF_DECnet
183         PF_DLI
184         PF_ECMA
185         PF_GOSIP
186         PF_HYLINK
187         PF_IMPLINK
188         PF_INET
189         PF_LAT
190         PF_MAX
191         PF_NBS
192         PF_NIT
193         PF_NS
194         PF_OSI
195         PF_OSINET
196         PF_PUP
197         PF_SNA
198         PF_UNIX
199         PF_UNSPEC
200         PF_X25
201         SOCK_DGRAM
202         SOCK_RAW
203         SOCK_RDM
204         SOCK_SEQPACKET
205         SOCK_STREAM
206         SOL_SOCKET
207         SOMAXCONN
208         SO_ACCEPTCONN
209         SO_BROADCAST
210         SO_DEBUG
211         SO_DONTLINGER
212         SO_DONTROUTE
213         SO_ERROR
214         SO_KEEPALIVE
215         SO_LINGER
216         SO_OOBINLINE
217         SO_RCVBUF
218         SO_RCVLOWAT
219         SO_RCVTIMEO
220         SO_REUSEADDR
221         SO_SNDBUF
222         SO_SNDLOWAT
223         SO_SNDTIMEO
224         SO_TYPE
225         SO_USELOOPBACK
226 );
227
228 sub sockaddr_in {
229     if (@_ == 6 && !wantarray) { # perl5.001m compat; use this && die
230         my($af, $port, @quad) = @_;
231         carp "6-ARG sockaddr_in call is deprecated" if $^W;
232         pack_sockaddr_in($port, inet_aton(join('.', @quad)));
233     } elsif (wantarray) {
234         croak "usage:   (port,iaddr) = sockaddr_in(sin_sv)" unless @_ == 1;
235         unpack_sockaddr_in(@_);
236     } else {
237         croak "usage:   sin_sv = sockaddr_in(port,iaddr))" unless @_ == 2;
238         pack_sockaddr_in(@_);
239     }
240 }
241
242 sub sockaddr_un {
243     if (wantarray) {
244         croak "usage:   (filename) = sockaddr_un(sun_sv)" unless @_ == 1;
245         unpack_sockaddr_un(@_);
246     } else {
247         croak "usage:   sun_sv = sockaddr_un(filename)" unless @_ == 1;
248         pack_sockaddr_un(@_);
249     }
250 }
251
252
253 sub AUTOLOAD {
254     my($constname);
255     ($constname = $AUTOLOAD) =~ s/.*:://;
256     my $val = constant($constname, @_ ? $_[0] : 0);
257     if ($! != 0) {
258         my ($pack,$file,$line) = caller;
259         croak "Your vendor has not defined Socket macro $constname, used";
260     }
261     eval "sub $AUTOLOAD { $val }";
262     goto &$AUTOLOAD;
263 }
264
265 bootstrap Socket $VERSION;
266
267 1;