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