This is a live mirror of the Perl 5 development currently hosted at https://github.com/perl/perl5
Fcntl: more O_ constants, move SEEK_ to @EXPORT_OK
[perl5.git] / ext / Socket / Socket.pm
CommitLineData
a0d0e21e 1package Socket;
73c78b0a 2
17f410f9 3our($VERSION, @ISA, @EXPORT, @EXPORT_OK, %EXPORT_TAGS);
1494e794 4$VERSION = "1.71";
3b35bae3
AD
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
AD
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
LW
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
LW
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
AD
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
LW
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
CN
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
AD
57In addition, some structure manipulation functions are available:
58
2ae324a7
PP
59=over
60
8e07c86e
AD
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
PP
66cannot be resolved, returns undef. For multi-homed hosts (hosts
67with more than one address), the first address found is returned.
8e07c86e
AD
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
AD
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
PP
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
AD
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
AD
103=item INADDR_NONE
104
105Note - does not return a number.
106
7e1af8bc 107Returns the 4-byte 'invalid' ip address. Normally equivalent
8e07c86e
AD
108to inet_aton('255.255.255.255').
109
4633a7c4
LW
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
LW
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
AD
127
128=item unpack_sockaddr_in SOCKADDR_IN
129
4633a7c4
LW
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
LW
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
LW
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
PP
158=back
159
3b35bae3
AD
160=cut
161
a0d0e21e
LW
162use Carp;
163
164require Exporter;
9426adcd
IZ
165use XSLoader ();
166@ISA = qw(Exporter);
a0d0e21e 167@EXPORT = qw(
8e07c86e 168 inet_aton inet_ntoa pack_sockaddr_in unpack_sockaddr_in
4633a7c4
LW
169 pack_sockaddr_un unpack_sockaddr_un
170 sockaddr_in sockaddr_un
7e1af8bc 171 INADDR_ANY INADDR_BROADCAST INADDR_LOOPBACK INADDR_NONE
a0d0e21e
LW
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
JH
196 IOV_MAX
197 MSG_BCAST
de4597cb
JH
198 MSG_CTLFLAGS
199 MSG_CTLIGNORE
200 MSG_CTRUNC
a0d0e21e 201 MSG_DONTROUTE
de4597cb
JH
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
LW
210 MSG_OOB
211 MSG_PEEK
de4597cb
JH
212 MSG_PROXY
213 MSG_RST
214 MSG_SYN
215 MSG_TRUNC
216 MSG_URG
217 MSG_WAITALL
a0d0e21e
LW
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
JH
242 SCM_CONNECT
243 SCM_CREDENTIALS
244 SCM_CREDS
245 SCM_RIGHTS
246 SCM_TIMESTAMP
ca6e1c26
JH
247 SHUT_RD
248 SHUT_RDWR
249 SHUT_WR
a0d0e21e
LW
250 SOCK_DGRAM
251 SOCK_RAW
252 SOCK_RDM
253 SOCK_SEQPACKET
254 SOCK_STREAM
255 SOL_SOCKET
256 SOMAXCONN
257 SO_ACCEPTCONN
258 SO_BROADCAST
259 SO_DEBUG
260 SO_DONTLINGER
261 SO_DONTROUTE
262 SO_ERROR
263 SO_KEEPALIVE
264 SO_LINGER
265 SO_OOBINLINE
266 SO_RCVBUF
267 SO_RCVLOWAT
268 SO_RCVTIMEO
269 SO_REUSEADDR
270 SO_SNDBUF
271 SO_SNDLOWAT
272 SO_SNDTIMEO
273 SO_TYPE
274 SO_USELOOPBACK
6b1016b5 275 UIO_MAXIOV
a0d0e21e
LW
276);
277
1494e794
JP
278@EXPORT_OK = qw(CR LF CRLF $CR $LF $CRLF
279
280 IPPROTO_TCP
281 TCP_KEEPALIVE
282 TCP_MAXRT
283 TCP_MAXSEG
284 TCP_NODELAY
285 TCP_STDURG);
fdb41d65
CN
286
287%EXPORT_TAGS = (
dde527fc 288 crlf => [qw(CR LF CRLF $CR $LF $CRLF)],
fdb41d65
CN
289 all => [@EXPORT, @EXPORT_OK],
290);
291
292BEGIN {
293 sub CR () {"\015"}
294 sub LF () {"\012"}
295 sub CRLF () {"\015\012"}
296}
297
298*CR = \CR();
299*LF = \LF();
300*CRLF = \CRLF();
301
4633a7c4
LW
302sub sockaddr_in {
303 if (@_ == 6 && !wantarray) { # perl5.001m compat; use this && die
304 my($af, $port, @quad) = @_;
305 carp "6-ARG sockaddr_in call is deprecated" if $^W;
306 pack_sockaddr_in($port, inet_aton(join('.', @quad)));
307 } elsif (wantarray) {
308 croak "usage: (port,iaddr) = sockaddr_in(sin_sv)" unless @_ == 1;
309 unpack_sockaddr_in(@_);
310 } else {
311 croak "usage: sin_sv = sockaddr_in(port,iaddr))" unless @_ == 2;
312 pack_sockaddr_in(@_);
313 }
314}
315
316sub sockaddr_un {
317 if (wantarray) {
318 croak "usage: (filename) = sockaddr_un(sun_sv)" unless @_ == 1;
319 unpack_sockaddr_un(@_);
320 } else {
37120919
AD
321 croak "usage: sun_sv = sockaddr_un(filename)" unless @_ == 1;
322 pack_sockaddr_un(@_);
4633a7c4
LW
323 }
324}
325
ca6e1c26
JH
326sub INADDR_ANY ();
327sub INADDR_BROADCAST ();
328sub INADDR_LOOPBACK ();
329sub INADDR_LOOPBACK ();
330
331sub AF_802 ();
332sub AF_APPLETALK ();
333sub AF_CCITT ();
334sub AF_CHAOS ();
335sub AF_DATAKIT ();
336sub AF_DECnet ();
337sub AF_DLI ();
338sub AF_ECMA ();
339sub AF_GOSIP ();
340sub AF_HYLINK ();
341sub AF_IMPLINK ();
342sub AF_INET ();
343sub AF_LAT ();
344sub AF_MAX ();
345sub AF_NBS ();
346sub AF_NIT ();
347sub AF_NS ();
348sub AF_OSI ();
349sub AF_OSINET ();
350sub AF_PUP ();
351sub AF_SNA ();
352sub AF_UNIX ();
353sub AF_UNSPEC ();
354sub AF_X25 ();
355sub IOV_MAX ();
356sub MSG_BCAST ();
357sub MSG_CTLFLAGS ();
358sub MSG_CTLIGNORE ();
359sub MSG_CTRUNC ();
360sub MSG_DONTROUTE ();
361sub MSG_DONTWAIT ();
362sub MSG_EOF ();
363sub MSG_EOR ();
364sub MSG_ERRQUEUE ();
365sub MSG_FIN ();
366sub MSG_MAXIOVLEN ();
367sub MSG_MCAST ();
368sub MSG_NOSIGNAL ();
369sub MSG_OOB ();
370sub MSG_PEEK ();
371sub MSG_PROXY ();
372sub MSG_RST ();
373sub MSG_SYN ();
374sub MSG_TRUNC ();
375sub MSG_URG ();
376sub MSG_WAITALL ();
377sub PF_802 ();
378sub PF_APPLETALK ();
379sub PF_CCITT ();
380sub PF_CHAOS ();
381sub PF_DATAKIT ();
382sub PF_DECnet ();
383sub PF_DLI ();
384sub PF_ECMA ();
385sub PF_GOSIP ();
386sub PF_HYLINK ();
387sub PF_IMPLINK ();
388sub PF_INET ();
389sub PF_LAT ();
390sub PF_MAX ();
391sub PF_NBS ();
392sub PF_NIT ();
393sub PF_NS ();
394sub PF_OSI ();
395sub PF_OSINET ();
396sub PF_PUP ();
397sub PF_SNA ();
398sub PF_UNIX ();
399sub PF_UNSPEC ();
400sub PF_X25 ();
401sub SCM_CONNECT ();
402sub SCM_CREDENTIALS ();
403sub SCM_CREDS ();
404sub SCM_RIGHTS ();
405sub SCM_TIMESTAMP ();
406sub SHUT_RD ();
407sub SHUT_RDWR ();
408sub SHUT_WR ();
409sub SOCK_DGRAM ();
410sub SOCK_RAW ();
411sub SOCK_RDM ();
412sub SOCK_SEQPACKET ();
413sub SOCK_STREAM ();
414sub SOL_SOCKET ();
415sub SOMAXCONN ();
416sub SO_ACCEPTCONN ();
417sub SO_BROADCAST ();
418sub SO_DEBUG ();
419sub SO_DONTLINGER ();
420sub SO_DONTROUTE ();
421sub SO_ERROR ();
422sub SO_KEEPALIVE ();
423sub SO_LINGER ();
424sub SO_OOBINLINE ();
425sub SO_RCVBUF ();
426sub SO_RCVLOWAT ();
427sub SO_RCVTIMEO ();
428sub SO_REUSEADDR ();
429sub SO_SNDBUF ();
430sub SO_SNDLOWAT ();
431sub SO_SNDTIMEO ();
432sub SO_TYPE ();
433sub SO_USELOOPBACK ();
434sub UIO_MAXIOV ();
4633a7c4 435
a0d0e21e 436sub AUTOLOAD {
73c78b0a 437 my($constname);
a0d0e21e 438 ($constname = $AUTOLOAD) =~ s/.*:://;
73c78b0a 439 my $val = constant($constname, @_ ? $_[0] : 0);
a0d0e21e 440 if ($! != 0) {
676d8cc7
AK
441 my ($pack,$file,$line) = caller;
442 croak "Your vendor has not defined Socket macro $constname, used";
a0d0e21e 443 }
ca6e1c26 444 eval "sub $AUTOLOAD () { $val }";
a0d0e21e
LW
445 goto &$AUTOLOAD;
446}
447
9426adcd 448XSLoader::load 'Socket', $VERSION;
a0d0e21e 449
a0d0e21e 4501;