severe bugs in change#3786 fixed
[p5sagit/p5-mst-13.2.git] / ext / Socket / Socket.pm
CommitLineData
a0d0e21e 1package Socket;
73c78b0a 2
fdb41d65 3use vars qw($VERSION @ISA @EXPORT @EXPORT_OK %EXPORT_TAGS);
1494e794 4$VERSION = "1.71";
3b35bae3 5
6=head1 NAME
7
cb1a09d0 8Socket, sockaddr_in, sockaddr_un, inet_aton, inet_ntoa - load the C socket.h defines and structure manipulators
3b35bae3 9
10=head1 SYNOPSIS
11
12 use Socket;
13
4633a7c4 14 $proto = getprotobyname('udp');
8e07c86e 15 socket(Socket_Handle, PF_INET, SOCK_DGRAM, $proto);
4633a7c4 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);
67d7c167 23 $port = getservbyname('smtp', 'tcp');
4633a7c4 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);
3b35bae3 38
39=head1 DESCRIPTION
40
41This module is just a translation of the C F<socket.h> file.
42Unlike the old mechanism of requiring a translated F<socket.ph>
43file, this uses the B<h2xs> program (see the Perl source distribution)
44and your native C compiler. This means that it has a
4633a7c4 45far more likely chance of getting the numbers right. This includes
46all of the commonly used pound-defines like AF_INET, SOCK_STREAM, etc.
3b35bae3 47
fdb41d65 48Also, some common socket "newline" constants are provided: the
49constants C<CR>, C<LF>, and C<CRLF>, as well as C<$CR>, C<$LF>, and
50C<$CRLF>, which map to C<\015>, C<\012>, and C<\015\012>. If you do
51not want to use the literal characters in your programs, then use
52the constants provided here. They are not exported by default, but can
53be imported individually, and with the C<:crlf> export tag:
54
55 use Socket qw(:DEFAULT :crlf);
56
8e07c86e 57In addition, some structure manipulation functions are available:
58
2ae324a7 59=over
60
8e07c86e 61=item inet_aton HOSTNAME
62
63Takes a string giving the name of a host, and translates that
64to the 4-byte string (structure). Takes arguments of both
65the 'rtfm.mit.edu' type and '18.181.0.24'. If the host name
7e1af8bc 66cannot be resolved, returns undef. For multi-homed hosts (hosts
67with more than one address), the first address found is returned.
8e07c86e 68
69=item inet_ntoa IP_ADDRESS
70
71Takes a four byte ip address (as returned by inet_aton())
72and translates it into a string of the form 'd.d.d.d'
73where the 'd's are numbers less than 256 (the normal
74readable four dotted number notation for internet addresses).
75
76=item INADDR_ANY
77
4633a7c4 78Note: does not return a number, but a packed string.
8e07c86e 79
80Returns the 4-byte wildcard ip address which specifies any
81of the hosts ip addresses. (A particular machine can have
82more than one ip address, each address corresponding to
83a particular network interface. This wildcard address
84allows you to bind to all of them simultaneously.)
85Normally equivalent to inet_aton('0.0.0.0').
86
7e1af8bc 87=item INADDR_BROADCAST
88
89Note: does not return a number, but a packed string.
90
91Returns the 4-byte 'this-lan' ip broadcast address.
92This can be useful for some protocols to solicit information
93from all servers on the same LAN cable.
94Normally equivalent to inet_aton('255.255.255.255').
95
8e07c86e 96=item INADDR_LOOPBACK
97
98Note - does not return a number.
99
100Returns the 4-byte loopback address. Normally equivalent
101to inet_aton('localhost').
3b35bae3 102
8e07c86e 103=item INADDR_NONE
104
105Note - does not return a number.
106
7e1af8bc 107Returns the 4-byte 'invalid' ip address. Normally equivalent
8e07c86e 108to inet_aton('255.255.255.255').
109
4633a7c4 110=item sockaddr_in PORT, ADDRESS
111
112=item sockaddr_in SOCKADDR_IN
113
114In an array context, unpacks its SOCKADDR_IN argument and returns an array
115consisting of (PORT, ADDRESS). In a scalar context, packs its (PORT,
116ADDRESS) arguments as a SOCKADDR_IN and returns it. If this is confusing,
117use pack_sockaddr_in() and unpack_sockaddr_in() explicitly.
118
119=item pack_sockaddr_in PORT, IP_ADDRESS
8e07c86e 120
4633a7c4 121Takes two arguments, a port number and a 4 byte IP_ADDRESS (as returned by
122inet_aton()). Returns the sockaddr_in structure with those arguments
123packed in with AF_INET filled in. For internet domain sockets, this
124structure is normally what you need for the arguments in bind(),
125connect(), and send(), and is also returned by getpeername(),
126getsockname() and recv().
8e07c86e 127
128=item unpack_sockaddr_in SOCKADDR_IN
129
4633a7c4 130Takes a sockaddr_in structure (as returned by pack_sockaddr_in()) and
131returns an array of two elements: the port and the 4-byte ip-address.
132Will croak if the structure does not have AF_INET in the right place.
133
134=item sockaddr_un PATHNAME
135
136=item sockaddr_un SOCKADDR_UN
137
138In an array context, unpacks its SOCKADDR_UN argument and returns an array
1fef88e7 139consisting of (PATHNAME). In a scalar context, packs its PATHNAME
4633a7c4 140arguments as a SOCKADDR_UN and returns it. If this is confusing, use
141pack_sockaddr_un() and unpack_sockaddr_un() explicitly.
1fef88e7 142These are only supported if your system has E<lt>F<sys/un.h>E<gt>.
4633a7c4 143
144=item pack_sockaddr_un PATH
145
146Takes one argument, a pathname. Returns the sockaddr_un structure with
147that path packed in with AF_UNIX filled in. For unix domain sockets, this
148structure is normally what you need for the arguments in bind(),
149connect(), and send(), and is also returned by getpeername(),
150getsockname() and recv().
151
152=item unpack_sockaddr_un SOCKADDR_UN
153
154Takes a sockaddr_un structure (as returned by pack_sockaddr_un())
155and returns the pathname. Will croak if the structure does not
156have AF_UNIX in the right place.
3b35bae3 157
2ae324a7 158=back
159
3b35bae3 160=cut
161
a0d0e21e 162use Carp;
163
164require Exporter;
9426adcd 165use XSLoader ();
166@ISA = qw(Exporter);
a0d0e21e 167@EXPORT = qw(
8e07c86e 168 inet_aton inet_ntoa pack_sockaddr_in unpack_sockaddr_in
4633a7c4 169 pack_sockaddr_un unpack_sockaddr_un
170 sockaddr_in sockaddr_un
7e1af8bc 171 INADDR_ANY INADDR_BROADCAST INADDR_LOOPBACK INADDR_NONE
a0d0e21e 172 AF_802
173 AF_APPLETALK
174 AF_CCITT
175 AF_CHAOS
176 AF_DATAKIT
177 AF_DECnet
178 AF_DLI
179 AF_ECMA
180 AF_GOSIP
181 AF_HYLINK
182 AF_IMPLINK
183 AF_INET
184 AF_LAT
185 AF_MAX
186 AF_NBS
187 AF_NIT
188 AF_NS
189 AF_OSI
190 AF_OSINET
191 AF_PUP
192 AF_SNA
193 AF_UNIX
194 AF_UNSPEC
195 AF_X25
6b1016b5 196 IOV_MAX
197 MSG_BCAST
de4597cb 198 MSG_CTLFLAGS
199 MSG_CTLIGNORE
200 MSG_CTRUNC
a0d0e21e 201 MSG_DONTROUTE
de4597cb 202 MSG_DONTWAIT
203 MSG_EOF
204 MSG_EOR
205 MSG_ERRQUEUE
206 MSG_FIN
a0d0e21e 207 MSG_MAXIOVLEN
6b1016b5 208 MSG_MCAST
de4597cb 209 MSG_NOSIGNAL
a0d0e21e 210 MSG_OOB
211 MSG_PEEK
de4597cb 212 MSG_PROXY
213 MSG_RST
214 MSG_SYN
215 MSG_TRUNC
216 MSG_URG
217 MSG_WAITALL
a0d0e21e 218 PF_802
219 PF_APPLETALK
220 PF_CCITT
221 PF_CHAOS
222 PF_DATAKIT
223 PF_DECnet
224 PF_DLI
225 PF_ECMA
226 PF_GOSIP
227 PF_HYLINK
228 PF_IMPLINK
229 PF_INET
230 PF_LAT
231 PF_MAX
232 PF_NBS
233 PF_NIT
234 PF_NS
235 PF_OSI
236 PF_OSINET
237 PF_PUP
238 PF_SNA
239 PF_UNIX
240 PF_UNSPEC
241 PF_X25
de4597cb 242 SCM_CONNECT
243 SCM_CREDENTIALS
244 SCM_CREDS
245 SCM_RIGHTS
246 SCM_TIMESTAMP
a0d0e21e 247 SOCK_DGRAM
248 SOCK_RAW
249 SOCK_RDM
250 SOCK_SEQPACKET
251 SOCK_STREAM
252 SOL_SOCKET
253 SOMAXCONN
254 SO_ACCEPTCONN
255 SO_BROADCAST
256 SO_DEBUG
257 SO_DONTLINGER
258 SO_DONTROUTE
259 SO_ERROR
260 SO_KEEPALIVE
261 SO_LINGER
262 SO_OOBINLINE
263 SO_RCVBUF
264 SO_RCVLOWAT
265 SO_RCVTIMEO
266 SO_REUSEADDR
267 SO_SNDBUF
268 SO_SNDLOWAT
269 SO_SNDTIMEO
270 SO_TYPE
271 SO_USELOOPBACK
6b1016b5 272 UIO_MAXIOV
a0d0e21e 273);
274
1494e794 275@EXPORT_OK = qw(CR LF CRLF $CR $LF $CRLF
276
277 IPPROTO_TCP
278 TCP_KEEPALIVE
279 TCP_MAXRT
280 TCP_MAXSEG
281 TCP_NODELAY
282 TCP_STDURG);
fdb41d65 283
284%EXPORT_TAGS = (
dde527fc 285 crlf => [qw(CR LF CRLF $CR $LF $CRLF)],
fdb41d65 286 all => [@EXPORT, @EXPORT_OK],
287);
288
289BEGIN {
290 sub CR () {"\015"}
291 sub LF () {"\012"}
292 sub CRLF () {"\015\012"}
293}
294
295*CR = \CR();
296*LF = \LF();
297*CRLF = \CRLF();
298
4633a7c4 299sub sockaddr_in {
300 if (@_ == 6 && !wantarray) { # perl5.001m compat; use this && die
301 my($af, $port, @quad) = @_;
302 carp "6-ARG sockaddr_in call is deprecated" if $^W;
303 pack_sockaddr_in($port, inet_aton(join('.', @quad)));
304 } elsif (wantarray) {
305 croak "usage: (port,iaddr) = sockaddr_in(sin_sv)" unless @_ == 1;
306 unpack_sockaddr_in(@_);
307 } else {
308 croak "usage: sin_sv = sockaddr_in(port,iaddr))" unless @_ == 2;
309 pack_sockaddr_in(@_);
310 }
311}
312
313sub sockaddr_un {
314 if (wantarray) {
315 croak "usage: (filename) = sockaddr_un(sun_sv)" unless @_ == 1;
316 unpack_sockaddr_un(@_);
317 } else {
37120919 318 croak "usage: sun_sv = sockaddr_un(filename)" unless @_ == 1;
319 pack_sockaddr_un(@_);
4633a7c4 320 }
321}
322
323
a0d0e21e 324sub AUTOLOAD {
73c78b0a 325 my($constname);
a0d0e21e 326 ($constname = $AUTOLOAD) =~ s/.*:://;
73c78b0a 327 my $val = constant($constname, @_ ? $_[0] : 0);
a0d0e21e 328 if ($! != 0) {
676d8cc7 329 my ($pack,$file,$line) = caller;
330 croak "Your vendor has not defined Socket macro $constname, used";
a0d0e21e 331 }
332 eval "sub $AUTOLOAD { $val }";
333 goto &$AUTOLOAD;
334}
335
9426adcd 336XSLoader::load 'Socket', $VERSION;
a0d0e21e 337
a0d0e21e 3381;