This is a live mirror of the Perl 5 development currently hosted at https://github.com/perl/perl5
[PATCH 1/3] Implement Socket::pack_sockaddr_in6() and unpack_sockaddr_in6()
[perl5.git] / ext / Socket / Socket.pm
CommitLineData
a0d0e21e 1package Socket;
73c78b0a 2
17f410f9 3our($VERSION, @ISA, @EXPORT, @EXPORT_OK, %EXPORT_TAGS);
735631af 4$VERSION = "1.91";
3b35bae3
AD
5
6=head1 NAME
7
036d8bd4 8Socket, sockaddr_in, sockaddr_un, inet_aton, inet_ntoa, inet_pton, inet_ntop - 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
PP
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 149
c73aa44c
PLE
150=item pack_sockaddr_in6 PORT, IP6_ADDRESS, [ SCOPE_ID, [ FLOWINFO ] ]
151
152Takes two to four arguments, a port number, an opaque string (as returned by
153inet_pton()), optionally a scope ID number, and optionally a flow label
154number. Returns the sockaddr_in6 structure with those arguments packed in
155with AF_INET6 filled in. IPv6 equivalent of pack_sockaddr_in().
156
157=item unpack_sockaddr_in6 SOCKADDR_IN6
158
159Takes a sockaddr_in6 structure (as returned by pack_sockaddr_in6()) and
160returns an array of four elements: the port number, an opaque string
161representing the IPv6 address, the scope ID, and the flow label. (You can
162use inet_ntop() to convert the address to the usual string format). Will
163croak if the structure does not have AF_INET6 in the right place.
164
4633a7c4
LW
165=item sockaddr_un PATHNAME
166
167=item sockaddr_un SOCKADDR_UN
168
91e74348 169In a list context, unpacks its SOCKADDR_UN argument and returns an array
1fef88e7 170consisting of (PATHNAME). In a scalar context, packs its PATHNAME
4633a7c4
LW
171arguments as a SOCKADDR_UN and returns it. If this is confusing, use
172pack_sockaddr_un() and unpack_sockaddr_un() explicitly.
1fef88e7 173These are only supported if your system has E<lt>F<sys/un.h>E<gt>.
4633a7c4
LW
174
175=item pack_sockaddr_un PATH
176
177Takes one argument, a pathname. Returns the sockaddr_un structure with
178that path packed in with AF_UNIX filled in. For unix domain sockets, this
179structure is normally what you need for the arguments in bind(),
180connect(), and send(), and is also returned by getpeername(),
181getsockname() and recv().
182
183=item unpack_sockaddr_un SOCKADDR_UN
184
185Takes a sockaddr_un structure (as returned by pack_sockaddr_un())
186and returns the pathname. Will croak if the structure does not
187have AF_UNIX in the right place.
3b35bae3 188
036d8bd4
SP
189=item inet_pton ADDRESS_FAMILY, HOSTNAME
190
191Takes an address family, either AF_INET or AF_INET6, and a string giving
192the name of a host, and translates that to an opaque string
193(if programming in C, struct in_addr or struct in6_addr depending on the
194address family passed in). The host string may be a string hostname, such
195as 'www.perl.org', or an IP address. If using an IP address, the type of
196IP address must be consistant with the address family passed into the function.
197
d6896be3
JV
198This function is not exported by default.
199
036d8bd4
SP
200=item inet_ntop ADDRESS_FAMILY, IP_ADDRESS
201
202Takes an address family, either AF_INET or AF_INET6, and a string
203(an opaque string as returned by inet_aton() or inet_pton()) and
204translates it to an IPv4 or IPv6 address string.
205
d6896be3
JV
206This function is not exported by default.
207
2ae324a7
PP
208=back
209
3b35bae3
AD
210=cut
211
a0d0e21e 212use Carp;
d3a7d8c7 213use warnings::register;
a0d0e21e
LW
214
215require Exporter;
da4061d3 216require XSLoader;
9426adcd 217@ISA = qw(Exporter);
a0d0e21e 218@EXPORT = qw(
2a84dff3
GA
219 inet_aton inet_ntoa
220 sockaddr_family
221 pack_sockaddr_in unpack_sockaddr_in
4633a7c4 222 pack_sockaddr_un unpack_sockaddr_un
c73aa44c 223 pack_sockaddr_in6 unpack_sockaddr_in6
4633a7c4 224 sockaddr_in sockaddr_un
7e1af8bc 225 INADDR_ANY INADDR_BROADCAST INADDR_LOOPBACK INADDR_NONE
a0d0e21e 226 AF_802
7198d2fd 227 AF_AAL
a0d0e21e
LW
228 AF_APPLETALK
229 AF_CCITT
230 AF_CHAOS
7198d2fd 231 AF_CTF
a0d0e21e
LW
232 AF_DATAKIT
233 AF_DECnet
234 AF_DLI
235 AF_ECMA
236 AF_GOSIP
237 AF_HYLINK
238 AF_IMPLINK
239 AF_INET
7198d2fd
JH
240 AF_INET6
241 AF_ISO
242 AF_KEY
243 AF_LAST
a0d0e21e 244 AF_LAT
7198d2fd 245 AF_LINK
a0d0e21e
LW
246 AF_MAX
247 AF_NBS
248 AF_NIT
249 AF_NS
250 AF_OSI
251 AF_OSINET
252 AF_PUP
7198d2fd 253 AF_ROUTE
a0d0e21e
LW
254 AF_SNA
255 AF_UNIX
256 AF_UNSPEC
7198d2fd
JH
257 AF_USER
258 AF_WAN
a0d0e21e 259 AF_X25
6b1016b5 260 IOV_MAX
131c565a
SP
261 IP_OPTIONS
262 IP_HDRINCL
263 IP_TOS
264 IP_TTL
265 IP_RECVOPTS
266 IP_RECVRETOPTS
267 IP_RETOPTS
6b1016b5 268 MSG_BCAST
7198d2fd 269 MSG_BTAG
de4597cb
JH
270 MSG_CTLFLAGS
271 MSG_CTLIGNORE
272 MSG_CTRUNC
a0d0e21e 273 MSG_DONTROUTE
de4597cb
JH
274 MSG_DONTWAIT
275 MSG_EOF
276 MSG_EOR
277 MSG_ERRQUEUE
7198d2fd 278 MSG_ETAG
de4597cb 279 MSG_FIN
a0d0e21e 280 MSG_MAXIOVLEN
6b1016b5 281 MSG_MCAST
de4597cb 282 MSG_NOSIGNAL
a0d0e21e
LW
283 MSG_OOB
284 MSG_PEEK
de4597cb
JH
285 MSG_PROXY
286 MSG_RST
287 MSG_SYN
288 MSG_TRUNC
289 MSG_URG
290 MSG_WAITALL
7198d2fd 291 MSG_WIRE
a0d0e21e 292 PF_802
7198d2fd 293 PF_AAL
a0d0e21e
LW
294 PF_APPLETALK
295 PF_CCITT
296 PF_CHAOS
7198d2fd 297 PF_CTF
a0d0e21e
LW
298 PF_DATAKIT
299 PF_DECnet
300 PF_DLI
301 PF_ECMA
302 PF_GOSIP
303 PF_HYLINK
304 PF_IMPLINK
305 PF_INET
7198d2fd
JH
306 PF_INET6
307 PF_ISO
308 PF_KEY
309 PF_LAST
a0d0e21e 310 PF_LAT
7198d2fd 311 PF_LINK
a0d0e21e
LW
312 PF_MAX
313 PF_NBS
314 PF_NIT
315 PF_NS
316 PF_OSI
317 PF_OSINET
318 PF_PUP
7198d2fd 319 PF_ROUTE
a0d0e21e
LW
320 PF_SNA
321 PF_UNIX
322 PF_UNSPEC
7198d2fd
JH
323 PF_USER
324 PF_WAN
a0d0e21e 325 PF_X25
de4597cb
JH
326 SCM_CONNECT
327 SCM_CREDENTIALS
328 SCM_CREDS
329 SCM_RIGHTS
330 SCM_TIMESTAMP
ca6e1c26
JH
331 SHUT_RD
332 SHUT_RDWR
333 SHUT_WR
a0d0e21e
LW
334 SOCK_DGRAM
335 SOCK_RAW
336 SOCK_RDM
337 SOCK_SEQPACKET
338 SOCK_STREAM
339 SOL_SOCKET
340 SOMAXCONN
341 SO_ACCEPTCONN
7198d2fd
JH
342 SO_ATTACH_FILTER
343 SO_BACKLOG
a0d0e21e 344 SO_BROADCAST
7198d2fd 345 SO_CHAMELEON
a0d0e21e 346 SO_DEBUG
7198d2fd
JH
347 SO_DETACH_FILTER
348 SO_DGRAM_ERRIND
a0d0e21e
LW
349 SO_DONTLINGER
350 SO_DONTROUTE
351 SO_ERROR
7198d2fd 352 SO_FAMILY
a0d0e21e
LW
353 SO_KEEPALIVE
354 SO_LINGER
355 SO_OOBINLINE
7198d2fd
JH
356 SO_PASSCRED
357 SO_PASSIFNAME
358 SO_PEERCRED
359 SO_PROTOCOL
360 SO_PROTOTYPE
a0d0e21e
LW
361 SO_RCVBUF
362 SO_RCVLOWAT
363 SO_RCVTIMEO
364 SO_REUSEADDR
b2f54bf3 365 SO_REUSEPORT
7198d2fd
JH
366 SO_SECURITY_AUTHENTICATION
367 SO_SECURITY_ENCRYPTION_NETWORK
368 SO_SECURITY_ENCRYPTION_TRANSPORT
a0d0e21e
LW
369 SO_SNDBUF
370 SO_SNDLOWAT
371 SO_SNDTIMEO
7198d2fd 372 SO_STATE
a0d0e21e
LW
373 SO_TYPE
374 SO_USELOOPBACK
7198d2fd
JH
375 SO_XOPEN
376 SO_XSE
6b1016b5 377 UIO_MAXIOV
a0d0e21e
LW
378);
379
1494e794
JP
380@EXPORT_OK = qw(CR LF CRLF $CR $LF $CRLF
381
d6896be3
JV
382 inet_pton
383 inet_ntop
384
131c565a
SP
385 IPPROTO_IP
386 IPPROTO_IPV6
387 IPPROTO_RAW
91c526f1 388 IPPROTO_ICMP
1494e794 389 IPPROTO_TCP
91c526f1
GA
390 IPPROTO_UDP
391
1494e794
JP
392 TCP_KEEPALIVE
393 TCP_MAXRT
394 TCP_MAXSEG
395 TCP_NODELAY
f686127b
SF
396 TCP_STDURG
397 TCP_CORK
398 TCP_KEEPIDLE
399 TCP_KEEPINTVL
400 TCP_KEEPCNT
401 TCP_SYNCNT
402 TCP_LINGER2
403 TCP_DEFER_ACCEPT
404 TCP_WINDOW_CLAMP
405 TCP_INFO
406 TCP_QUICKACK
407 TCP_CONGESTION
408 TCP_MD5SIG);
fdb41d65
CN
409
410%EXPORT_TAGS = (
dde527fc 411 crlf => [qw(CR LF CRLF $CR $LF $CRLF)],
fdb41d65
CN
412 all => [@EXPORT, @EXPORT_OK],
413);
414
415BEGIN {
416 sub CR () {"\015"}
417 sub LF () {"\012"}
418 sub CRLF () {"\015\012"}
419}
420
421*CR = \CR();
422*LF = \LF();
423*CRLF = \CRLF();
424
4633a7c4
LW
425sub sockaddr_in {
426 if (@_ == 6 && !wantarray) { # perl5.001m compat; use this && die
427 my($af, $port, @quad) = @_;
d3a7d8c7
GS
428 warnings::warn "6-ARG sockaddr_in call is deprecated"
429 if warnings::enabled();
4633a7c4
LW
430 pack_sockaddr_in($port, inet_aton(join('.', @quad)));
431 } elsif (wantarray) {
432 croak "usage: (port,iaddr) = sockaddr_in(sin_sv)" unless @_ == 1;
433 unpack_sockaddr_in(@_);
434 } else {
435 croak "usage: sin_sv = sockaddr_in(port,iaddr))" unless @_ == 2;
436 pack_sockaddr_in(@_);
437 }
438}
439
440sub sockaddr_un {
441 if (wantarray) {
442 croak "usage: (filename) = sockaddr_un(sun_sv)" unless @_ == 1;
443 unpack_sockaddr_un(@_);
444 } else {
37120919
AD
445 croak "usage: sun_sv = sockaddr_un(filename)" unless @_ == 1;
446 pack_sockaddr_un(@_);
4633a7c4
LW
447 }
448}
449
da4061d3 450XSLoader::load();
a0d0e21e 451
a0d0e21e 4521;