$VERSION "a5" doesn't quite work.
[p5sagit/p5-mst-13.2.git] / ext / Socket / Socket.pm
1 package Socket;
2
3 our($VERSION, @ISA, @EXPORT, @EXPORT_OK, %EXPORT_TAGS);
4 $VERSION = "1.75";
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', '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('/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 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_in PORT, ADDRESS
116
117 =item sockaddr_in SOCKADDR_IN
118
119 In a list context, unpacks its SOCKADDR_IN argument and returns an array
120 consisting of (PORT, ADDRESS).  In a scalar context, packs its (PORT,
121 ADDRESS) arguments as a SOCKADDR_IN and returns it.  If this is confusing,
122 use pack_sockaddr_in() and unpack_sockaddr_in() explicitly.
123
124 =item pack_sockaddr_in PORT, IP_ADDRESS
125
126 Takes two arguments, a port number and an opaque string, IP_ADDRESS
127 (as returned by inet_aton(), or a v-string).  Returns the sockaddr_in
128 structure with those arguments packed in with AF_INET filled in.  For
129 Internet domain sockets, this structure is normally what you need for
130 the arguments in bind(), connect(), and send(), and is also returned
131 by getpeername(), getsockname() and recv().
132
133 =item unpack_sockaddr_in SOCKADDR_IN
134
135 Takes a sockaddr_in structure (as returned by pack_sockaddr_in()) and
136 returns an array of two elements: the port and an opaque string
137 representing the IP address (you can use inet_ntoa() to convert the
138 address to the four-dotted numeric format).  Will croak if the
139 structure does not have AF_INET in the right place.
140
141 =item sockaddr_un PATHNAME
142
143 =item sockaddr_un SOCKADDR_UN
144
145 In a list context, unpacks its SOCKADDR_UN argument and returns an array
146 consisting of (PATHNAME).  In a scalar context, packs its PATHNAME
147 arguments as a SOCKADDR_UN and returns it.  If this is confusing, use
148 pack_sockaddr_un() and unpack_sockaddr_un() explicitly.
149 These are only supported if your system has E<lt>F<sys/un.h>E<gt>.
150
151 =item pack_sockaddr_un PATH
152
153 Takes one argument, a pathname. Returns the sockaddr_un structure with
154 that path packed in with AF_UNIX filled in. For unix domain sockets, this
155 structure is normally what you need for the arguments in bind(),
156 connect(), and send(), and is also returned by getpeername(),
157 getsockname() and recv().
158
159 =item unpack_sockaddr_un SOCKADDR_UN
160
161 Takes a sockaddr_un structure (as returned by pack_sockaddr_un())
162 and returns the pathname.  Will croak if the structure does not
163 have AF_UNIX in the right place.
164
165 =back
166
167 =cut
168
169 use Carp;
170 use warnings::register;
171
172 require Exporter;
173 use XSLoader ();
174 @ISA = qw(Exporter);
175 @EXPORT = qw(
176         inet_aton inet_ntoa pack_sockaddr_in unpack_sockaddr_in
177         pack_sockaddr_un unpack_sockaddr_un
178         sockaddr_in sockaddr_un
179         INADDR_ANY INADDR_BROADCAST INADDR_LOOPBACK INADDR_NONE
180         AF_802
181         AF_APPLETALK
182         AF_CCITT
183         AF_CHAOS
184         AF_DATAKIT
185         AF_DECnet
186         AF_DLI
187         AF_ECMA
188         AF_GOSIP
189         AF_HYLINK
190         AF_IMPLINK
191         AF_INET
192         AF_LAT
193         AF_MAX
194         AF_NBS
195         AF_NIT
196         AF_NS
197         AF_OSI
198         AF_OSINET
199         AF_PUP
200         AF_SNA
201         AF_UNIX
202         AF_UNSPEC
203         AF_X25
204         IOV_MAX
205         MSG_BCAST
206         MSG_CTLFLAGS
207         MSG_CTLIGNORE
208         MSG_CTRUNC
209         MSG_DONTROUTE
210         MSG_DONTWAIT
211         MSG_EOF
212         MSG_EOR
213         MSG_ERRQUEUE
214         MSG_FIN
215         MSG_MAXIOVLEN
216         MSG_MCAST
217         MSG_NOSIGNAL
218         MSG_OOB
219         MSG_PEEK
220         MSG_PROXY
221         MSG_RST
222         MSG_SYN
223         MSG_TRUNC
224         MSG_URG
225         MSG_WAITALL
226         PF_802
227         PF_APPLETALK
228         PF_CCITT
229         PF_CHAOS
230         PF_DATAKIT
231         PF_DECnet
232         PF_DLI
233         PF_ECMA
234         PF_GOSIP
235         PF_HYLINK
236         PF_IMPLINK
237         PF_INET
238         PF_LAT
239         PF_MAX
240         PF_NBS
241         PF_NIT
242         PF_NS
243         PF_OSI
244         PF_OSINET
245         PF_PUP
246         PF_SNA
247         PF_UNIX
248         PF_UNSPEC
249         PF_X25
250         SCM_CONNECT
251         SCM_CREDENTIALS
252         SCM_CREDS
253         SCM_RIGHTS
254         SCM_TIMESTAMP
255         SHUT_RD
256         SHUT_RDWR
257         SHUT_WR
258         SOCK_DGRAM
259         SOCK_RAW
260         SOCK_RDM
261         SOCK_SEQPACKET
262         SOCK_STREAM
263         SOL_SOCKET
264         SOMAXCONN
265         SO_ACCEPTCONN
266         SO_BROADCAST
267         SO_DEBUG
268         SO_DONTLINGER
269         SO_DONTROUTE
270         SO_ERROR
271         SO_KEEPALIVE
272         SO_LINGER
273         SO_OOBINLINE
274         SO_RCVBUF
275         SO_RCVLOWAT
276         SO_RCVTIMEO
277         SO_REUSEADDR
278         SO_REUSEPORT
279         SO_SNDBUF
280         SO_SNDLOWAT
281         SO_SNDTIMEO
282         SO_TYPE
283         SO_USELOOPBACK
284         UIO_MAXIOV
285 );
286
287 @EXPORT_OK = qw(CR LF CRLF $CR $LF $CRLF
288
289                IPPROTO_TCP
290                TCP_KEEPALIVE
291                TCP_MAXRT
292                TCP_MAXSEG
293                TCP_NODELAY
294                TCP_STDURG);
295
296 %EXPORT_TAGS = (
297     crlf    => [qw(CR LF CRLF $CR $LF $CRLF)],
298     all     => [@EXPORT, @EXPORT_OK],
299 );
300
301 BEGIN {
302     sub CR   () {"\015"}
303     sub LF   () {"\012"}
304     sub CRLF () {"\015\012"}
305 }
306
307 *CR   = \CR();
308 *LF   = \LF();
309 *CRLF = \CRLF();
310
311 sub sockaddr_in {
312     if (@_ == 6 && !wantarray) { # perl5.001m compat; use this && die
313         my($af, $port, @quad) = @_;
314         warnings::warn "6-ARG sockaddr_in call is deprecated" 
315             if warnings::enabled();
316         pack_sockaddr_in($port, inet_aton(join('.', @quad)));
317     } elsif (wantarray) {
318         croak "usage:   (port,iaddr) = sockaddr_in(sin_sv)" unless @_ == 1;
319         unpack_sockaddr_in(@_);
320     } else {
321         croak "usage:   sin_sv = sockaddr_in(port,iaddr))" unless @_ == 2;
322         pack_sockaddr_in(@_);
323     }
324 }
325
326 sub sockaddr_un {
327     if (wantarray) {
328         croak "usage:   (filename) = sockaddr_un(sun_sv)" unless @_ == 1;
329         unpack_sockaddr_un(@_);
330     } else {
331         croak "usage:   sun_sv = sockaddr_un(filename)" unless @_ == 1;
332         pack_sockaddr_un(@_);
333     }
334 }
335
336 sub AUTOLOAD {
337     my($constname);
338     ($constname = $AUTOLOAD) =~ s/.*:://;
339     croak "&Socket::constant not defined" if $constname eq 'constant';
340     my ($error, $val) = constant($constname);
341     if ($error) {
342         croak $error;
343     }
344     *$AUTOLOAD = sub { $val };
345     goto &$AUTOLOAD;
346 }
347
348 XSLoader::load 'Socket', $VERSION;
349
350 1;