Bump version of Socket.pm
[perl.git] / ext / Socket / Socket.pm
1 package Socket;
2
3 our($VERSION, @ISA, @EXPORT, @EXPORT_OK, %EXPORT_TAGS);
4 $VERSION = "1.84";
5
6 =head1 NAME
7
8 Socket, sockaddr_in, sockaddr_un, inet_aton, inet_ntoa, inet_pton, inet_ntop - 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', 'tcp');
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('/var/run/usock');
36     $sun = sockaddr_un('/var/run/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 Also, some common socket "newline" constants are provided: the
49 constants C<CR>, C<LF>, and C<CRLF>, as well as C<$CR>, C<$LF>, and
50 C<$CRLF>, which map to C<\015>, C<\012>, and C<\015\012>.  If you do
51 not want to use the literal characters in your programs, then use
52 the constants provided here.  They are not exported by default, but can
53 be imported individually, and with the C<:crlf> export tag:
54
55     use Socket qw(:DEFAULT :crlf);
56
57 In addition, some structure manipulation functions are available:
58
59 =over 4
60
61 =item inet_aton HOSTNAME
62
63 Takes a string giving the name of a host, and translates that to an
64 opaque string (if programming in C, struct in_addr). Takes arguments
65 of both the 'rtfm.mit.edu' type and '18.181.0.24'. If the host name
66 cannot be resolved, returns undef.  For multi-homed hosts (hosts with
67 more than one address), the first address found is returned.
68
69 For portability do not assume that the result of inet_aton() is 32
70 bits wide, in other words, that it would contain only the IPv4 address
71 in network order.
72
73 =item inet_ntoa IP_ADDRESS
74
75 Takes a string (an opaque string as returned by inet_aton(),
76 or a v-string representing the four octets of the IPv4 address in
77 network order) and translates it into a string of the form 'd.d.d.d'
78 where the 'd's are numbers less than 256 (the normal human-readable
79 four dotted number notation for Internet addresses).
80
81 =item INADDR_ANY
82
83 Note: does not return a number, but a packed string.
84
85 Returns the 4-byte wildcard ip address which specifies any
86 of the hosts ip addresses.  (A particular machine can have
87 more than one ip address, each address corresponding to
88 a particular network interface. This wildcard address
89 allows you to bind to all of them simultaneously.)
90 Normally equivalent to inet_aton('0.0.0.0').
91
92 =item INADDR_BROADCAST
93
94 Note: does not return a number, but a packed string.
95
96 Returns the 4-byte 'this-lan' ip broadcast address.
97 This can be useful for some protocols to solicit information
98 from all servers on the same LAN cable.
99 Normally equivalent to inet_aton('255.255.255.255').
100
101 =item INADDR_LOOPBACK
102
103 Note - does not return a number.
104
105 Returns the 4-byte loopback address.  Normally equivalent
106 to inet_aton('localhost').
107
108 =item INADDR_NONE
109
110 Note - does not return a number.
111
112 Returns the 4-byte 'invalid' ip address.  Normally equivalent
113 to inet_aton('255.255.255.255').
114
115 =item sockaddr_family SOCKADDR
116
117 Takes a sockaddr structure (as returned by pack_sockaddr_in(),
118 pack_sockaddr_un() or the perl builtin functions getsockname() and
119 getpeername()) and returns the address family tag.  It will match the
120 constant AF_INET for a sockaddr_in and AF_UNIX for a sockaddr_un.  It
121 can be used to figure out what unpacker to use for a sockaddr of
122 unknown type.
123
124 =item sockaddr_in PORT, ADDRESS
125
126 =item sockaddr_in SOCKADDR_IN
127
128 In a list context, unpacks its SOCKADDR_IN argument and returns an array
129 consisting of (PORT, ADDRESS).  In a scalar context, packs its (PORT,
130 ADDRESS) arguments as a SOCKADDR_IN and returns it.  If this is confusing,
131 use pack_sockaddr_in() and unpack_sockaddr_in() explicitly.
132
133 =item pack_sockaddr_in PORT, IP_ADDRESS
134
135 Takes two arguments, a port number and an opaque string, IP_ADDRESS
136 (as returned by inet_aton(), or a v-string).  Returns the sockaddr_in
137 structure with those arguments packed in with AF_INET filled in.  For
138 Internet domain sockets, this structure is normally what you need for
139 the arguments in bind(), connect(), and send(), and is also returned
140 by getpeername(), getsockname() and recv().
141
142 =item unpack_sockaddr_in SOCKADDR_IN
143
144 Takes a sockaddr_in structure (as returned by pack_sockaddr_in()) and
145 returns an array of two elements: the port and an opaque string
146 representing the IP address (you can use inet_ntoa() to convert the
147 address to the four-dotted numeric format).  Will croak if the
148 structure does not have AF_INET in the right place.
149
150 =item sockaddr_un PATHNAME
151
152 =item sockaddr_un SOCKADDR_UN
153
154 In a list context, unpacks its SOCKADDR_UN argument and returns an array
155 consisting of (PATHNAME).  In a scalar context, packs its PATHNAME
156 arguments as a SOCKADDR_UN and returns it.  If this is confusing, use
157 pack_sockaddr_un() and unpack_sockaddr_un() explicitly.
158 These are only supported if your system has E<lt>F<sys/un.h>E<gt>.
159
160 =item pack_sockaddr_un PATH
161
162 Takes one argument, a pathname. Returns the sockaddr_un structure with
163 that path packed in with AF_UNIX filled in. For unix domain sockets, this
164 structure is normally what you need for the arguments in bind(),
165 connect(), and send(), and is also returned by getpeername(),
166 getsockname() and recv().
167
168 =item unpack_sockaddr_un SOCKADDR_UN
169
170 Takes a sockaddr_un structure (as returned by pack_sockaddr_un())
171 and returns the pathname.  Will croak if the structure does not
172 have AF_UNIX in the right place.
173
174 =item inet_pton ADDRESS_FAMILY, HOSTNAME
175
176 Takes an address family, either AF_INET or AF_INET6, and a string giving
177 the name of a host, and translates that to an opaque string
178 (if programming in C, struct in_addr or struct in6_addr depending on the 
179 address family passed in).  The host string may be a string hostname, such
180 as 'www.perl.org', or an IP address.  If using an IP address, the type of
181 IP address must be consistant with the address family passed into the function.
182
183 =item inet_ntop ADDRESS_FAMILY, IP_ADDRESS
184
185 Takes an address family, either AF_INET or AF_INET6, and a string 
186 (an opaque string as returned by inet_aton() or inet_pton()) and
187 translates it to an IPv4 or IPv6 address string.
188
189 =back
190
191 =cut
192
193 use Carp;
194 use warnings::register;
195
196 require Exporter;
197 use XSLoader ();
198 @ISA = qw(Exporter);
199 @EXPORT = qw(
200         inet_aton inet_ntoa
201         inet_pton inet_ntop
202         sockaddr_family
203         pack_sockaddr_in unpack_sockaddr_in
204         pack_sockaddr_un unpack_sockaddr_un
205         sockaddr_in sockaddr_un
206         INADDR_ANY INADDR_BROADCAST INADDR_LOOPBACK INADDR_NONE
207         AF_802
208         AF_AAL
209         AF_APPLETALK
210         AF_CCITT
211         AF_CHAOS
212         AF_CTF
213         AF_DATAKIT
214         AF_DECnet
215         AF_DLI
216         AF_ECMA
217         AF_GOSIP
218         AF_HYLINK
219         AF_IMPLINK
220         AF_INET
221         AF_INET6
222         AF_ISO
223         AF_KEY
224         AF_LAST
225         AF_LAT
226         AF_LINK
227         AF_MAX
228         AF_NBS
229         AF_NIT
230         AF_NS
231         AF_OSI
232         AF_OSINET
233         AF_PUP
234         AF_ROUTE
235         AF_SNA
236         AF_UNIX
237         AF_UNSPEC
238         AF_USER
239         AF_WAN
240         AF_X25
241         IOV_MAX
242         IP_OPTIONS
243         IP_HDRINCL
244         IP_TOS
245         IP_TTL
246         IP_RECVOPTS
247         IP_RECVRETOPTS
248         IP_RETOPTS
249         MSG_BCAST
250         MSG_BTAG
251         MSG_CTLFLAGS
252         MSG_CTLIGNORE
253         MSG_CTRUNC
254         MSG_DONTROUTE
255         MSG_DONTWAIT
256         MSG_EOF
257         MSG_EOR
258         MSG_ERRQUEUE
259         MSG_ETAG
260         MSG_FIN
261         MSG_MAXIOVLEN
262         MSG_MCAST
263         MSG_NOSIGNAL
264         MSG_OOB
265         MSG_PEEK
266         MSG_PROXY
267         MSG_RST
268         MSG_SYN
269         MSG_TRUNC
270         MSG_URG
271         MSG_WAITALL
272         MSG_WIRE
273         PF_802
274         PF_AAL
275         PF_APPLETALK
276         PF_CCITT
277         PF_CHAOS
278         PF_CTF
279         PF_DATAKIT
280         PF_DECnet
281         PF_DLI
282         PF_ECMA
283         PF_GOSIP
284         PF_HYLINK
285         PF_IMPLINK
286         PF_INET
287         PF_INET6
288         PF_ISO
289         PF_KEY
290         PF_LAST
291         PF_LAT
292         PF_LINK
293         PF_MAX
294         PF_NBS
295         PF_NIT
296         PF_NS
297         PF_OSI
298         PF_OSINET
299         PF_PUP
300         PF_ROUTE
301         PF_SNA
302         PF_UNIX
303         PF_UNSPEC
304         PF_USER
305         PF_WAN
306         PF_X25
307         SCM_CONNECT
308         SCM_CREDENTIALS
309         SCM_CREDS
310         SCM_RIGHTS
311         SCM_TIMESTAMP
312         SHUT_RD
313         SHUT_RDWR
314         SHUT_WR
315         SOCK_DGRAM
316         SOCK_RAW
317         SOCK_RDM
318         SOCK_SEQPACKET
319         SOCK_STREAM
320         SOL_SOCKET
321         SOMAXCONN
322         SO_ACCEPTCONN
323         SO_ATTACH_FILTER
324         SO_BACKLOG
325         SO_BROADCAST
326         SO_CHAMELEON
327         SO_DEBUG
328         SO_DETACH_FILTER
329         SO_DGRAM_ERRIND
330         SO_DONTLINGER
331         SO_DONTROUTE
332         SO_ERROR
333         SO_FAMILY
334         SO_KEEPALIVE
335         SO_LINGER
336         SO_OOBINLINE
337         SO_PASSCRED
338         SO_PASSIFNAME
339         SO_PEERCRED
340         SO_PROTOCOL
341         SO_PROTOTYPE
342         SO_RCVBUF
343         SO_RCVLOWAT
344         SO_RCVTIMEO
345         SO_REUSEADDR
346         SO_REUSEPORT
347         SO_SECURITY_AUTHENTICATION
348         SO_SECURITY_ENCRYPTION_NETWORK
349         SO_SECURITY_ENCRYPTION_TRANSPORT
350         SO_SNDBUF
351         SO_SNDLOWAT
352         SO_SNDTIMEO
353         SO_STATE
354         SO_TYPE
355         SO_USELOOPBACK
356         SO_XOPEN
357         SO_XSE
358         UIO_MAXIOV
359 );
360
361 @EXPORT_OK = qw(CR LF CRLF $CR $LF $CRLF
362
363                IPPROTO_IP
364                IPPROTO_IPV6
365                IPPROTO_RAW
366                IPPROTO_ICMP
367                IPPROTO_TCP
368                IPPROTO_UDP
369
370                TCP_KEEPALIVE
371                TCP_MAXRT
372                TCP_MAXSEG
373                TCP_NODELAY
374                TCP_STDURG);
375
376 %EXPORT_TAGS = (
377     crlf    => [qw(CR LF CRLF $CR $LF $CRLF)],
378     all     => [@EXPORT, @EXPORT_OK],
379 );
380
381 BEGIN {
382     sub CR   () {"\015"}
383     sub LF   () {"\012"}
384     sub CRLF () {"\015\012"}
385 }
386
387 *CR   = \CR();
388 *LF   = \LF();
389 *CRLF = \CRLF();
390
391 sub sockaddr_in {
392     if (@_ == 6 && !wantarray) { # perl5.001m compat; use this && die
393         my($af, $port, @quad) = @_;
394         warnings::warn "6-ARG sockaddr_in call is deprecated" 
395             if warnings::enabled();
396         pack_sockaddr_in($port, inet_aton(join('.', @quad)));
397     } elsif (wantarray) {
398         croak "usage:   (port,iaddr) = sockaddr_in(sin_sv)" unless @_ == 1;
399         unpack_sockaddr_in(@_);
400     } else {
401         croak "usage:   sin_sv = sockaddr_in(port,iaddr))" unless @_ == 2;
402         pack_sockaddr_in(@_);
403     }
404 }
405
406 sub sockaddr_un {
407     if (wantarray) {
408         croak "usage:   (filename) = sockaddr_un(sun_sv)" unless @_ == 1;
409         unpack_sockaddr_un(@_);
410     } else {
411         croak "usage:   sun_sv = sockaddr_un(filename)" unless @_ == 1;
412         pack_sockaddr_un(@_);
413     }
414 }
415
416 sub AUTOLOAD {
417     my($constname);
418     ($constname = $AUTOLOAD) =~ s/.*:://;
419     croak "&Socket::constant not defined" if $constname eq 'constant';
420     my ($error, $val) = constant($constname);
421     if ($error) {
422         croak $error;
423     }
424     *$AUTOLOAD = sub { $val };
425     goto &$AUTOLOAD;
426 }
427
428 XSLoader::load 'Socket', $VERSION;
429
430 1;