This is a live mirror of the Perl 5 development currently hosted at https://github.com/perl/perl5
Style issue
[perl5.git] / ext / Socket / Socket.pm
CommitLineData
a0d0e21e 1package Socket;
73c78b0a 2
17f410f9 3our($VERSION, @ISA, @EXPORT, @EXPORT_OK, %EXPORT_TAGS);
6fe628c6 4$VERSION = "1.75";
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
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
4633a7c4
LW
115=item sockaddr_in PORT, ADDRESS
116
117=item sockaddr_in SOCKADDR_IN
118
91e74348 119In a list context, unpacks its SOCKADDR_IN argument and returns an array
4633a7c4
LW
120consisting of (PORT, ADDRESS). In a scalar context, packs its (PORT,
121ADDRESS) arguments as a SOCKADDR_IN and returns it. If this is confusing,
122use pack_sockaddr_in() and unpack_sockaddr_in() explicitly.
123
124=item pack_sockaddr_in PORT, IP_ADDRESS
8e07c86e 125
6fe628c6
JH
126Takes 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
128structure with those arguments packed in with AF_INET filled in. For
129Internet domain sockets, this structure is normally what you need for
130the arguments in bind(), connect(), and send(), and is also returned
131by getpeername(), getsockname() and recv().
8e07c86e
AD
132
133=item unpack_sockaddr_in SOCKADDR_IN
134
4633a7c4 135Takes a sockaddr_in structure (as returned by pack_sockaddr_in()) and
6fe628c6
JH
136returns an array of two elements: the port and an opaque string
137representing the IP address (you can use inet_ntoa() to convert the
138address to the four-dotted numeric format). Will croak if the
139structure does not have AF_INET in the right place.
4633a7c4
LW
140
141=item sockaddr_un PATHNAME
142
143=item sockaddr_un SOCKADDR_UN
144
91e74348 145In a list context, unpacks its SOCKADDR_UN argument and returns an array
1fef88e7 146consisting of (PATHNAME). In a scalar context, packs its PATHNAME
4633a7c4
LW
147arguments as a SOCKADDR_UN and returns it. If this is confusing, use
148pack_sockaddr_un() and unpack_sockaddr_un() explicitly.
1fef88e7 149These are only supported if your system has E<lt>F<sys/un.h>E<gt>.
4633a7c4
LW
150
151=item pack_sockaddr_un PATH
152
153Takes one argument, a pathname. Returns the sockaddr_un structure with
154that path packed in with AF_UNIX filled in. For unix domain sockets, this
155structure is normally what you need for the arguments in bind(),
156connect(), and send(), and is also returned by getpeername(),
157getsockname() and recv().
158
159=item unpack_sockaddr_un SOCKADDR_UN
160
161Takes a sockaddr_un structure (as returned by pack_sockaddr_un())
162and returns the pathname. Will croak if the structure does not
163have AF_UNIX in the right place.
3b35bae3 164
2ae324a7
PP
165=back
166
3b35bae3
AD
167=cut
168
a0d0e21e 169use Carp;
d3a7d8c7 170use warnings::register;
a0d0e21e
LW
171
172require Exporter;
9426adcd
IZ
173use XSLoader ();
174@ISA = qw(Exporter);
a0d0e21e 175@EXPORT = qw(
8e07c86e 176 inet_aton inet_ntoa pack_sockaddr_in unpack_sockaddr_in
4633a7c4
LW
177 pack_sockaddr_un unpack_sockaddr_un
178 sockaddr_in sockaddr_un
7e1af8bc 179 INADDR_ANY INADDR_BROADCAST INADDR_LOOPBACK INADDR_NONE
a0d0e21e 180 AF_802
7198d2fd 181 AF_AAL
a0d0e21e
LW
182 AF_APPLETALK
183 AF_CCITT
184 AF_CHAOS
7198d2fd 185 AF_CTF
a0d0e21e
LW
186 AF_DATAKIT
187 AF_DECnet
188 AF_DLI
189 AF_ECMA
190 AF_GOSIP
191 AF_HYLINK
192 AF_IMPLINK
193 AF_INET
7198d2fd
JH
194 AF_INET6
195 AF_ISO
196 AF_KEY
197 AF_LAST
a0d0e21e 198 AF_LAT
7198d2fd 199 AF_LINK
a0d0e21e
LW
200 AF_MAX
201 AF_NBS
202 AF_NIT
203 AF_NS
204 AF_OSI
205 AF_OSINET
206 AF_PUP
7198d2fd 207 AF_ROUTE
a0d0e21e
LW
208 AF_SNA
209 AF_UNIX
210 AF_UNSPEC
7198d2fd
JH
211 AF_USER
212 AF_WAN
a0d0e21e 213 AF_X25
6b1016b5
JH
214 IOV_MAX
215 MSG_BCAST
7198d2fd 216 MSG_BTAG
de4597cb
JH
217 MSG_CTLFLAGS
218 MSG_CTLIGNORE
219 MSG_CTRUNC
a0d0e21e 220 MSG_DONTROUTE
de4597cb
JH
221 MSG_DONTWAIT
222 MSG_EOF
223 MSG_EOR
224 MSG_ERRQUEUE
7198d2fd 225 MSG_ETAG
de4597cb 226 MSG_FIN
a0d0e21e 227 MSG_MAXIOVLEN
6b1016b5 228 MSG_MCAST
de4597cb 229 MSG_NOSIGNAL
a0d0e21e
LW
230 MSG_OOB
231 MSG_PEEK
de4597cb
JH
232 MSG_PROXY
233 MSG_RST
234 MSG_SYN
235 MSG_TRUNC
236 MSG_URG
237 MSG_WAITALL
7198d2fd 238 MSG_WIRE
a0d0e21e 239 PF_802
7198d2fd 240 PF_AAL
a0d0e21e
LW
241 PF_APPLETALK
242 PF_CCITT
243 PF_CHAOS
7198d2fd 244 PF_CTF
a0d0e21e
LW
245 PF_DATAKIT
246 PF_DECnet
247 PF_DLI
248 PF_ECMA
249 PF_GOSIP
250 PF_HYLINK
251 PF_IMPLINK
252 PF_INET
7198d2fd
JH
253 PF_INET6
254 PF_ISO
255 PF_KEY
256 PF_LAST
a0d0e21e 257 PF_LAT
7198d2fd 258 PF_LINK
a0d0e21e
LW
259 PF_MAX
260 PF_NBS
261 PF_NIT
262 PF_NS
263 PF_OSI
264 PF_OSINET
265 PF_PUP
7198d2fd 266 PF_ROUTE
a0d0e21e
LW
267 PF_SNA
268 PF_UNIX
269 PF_UNSPEC
7198d2fd
JH
270 PF_USER
271 PF_WAN
a0d0e21e 272 PF_X25
de4597cb
JH
273 SCM_CONNECT
274 SCM_CREDENTIALS
275 SCM_CREDS
276 SCM_RIGHTS
277 SCM_TIMESTAMP
ca6e1c26
JH
278 SHUT_RD
279 SHUT_RDWR
280 SHUT_WR
a0d0e21e
LW
281 SOCK_DGRAM
282 SOCK_RAW
283 SOCK_RDM
284 SOCK_SEQPACKET
285 SOCK_STREAM
286 SOL_SOCKET
287 SOMAXCONN
288 SO_ACCEPTCONN
7198d2fd
JH
289 SO_ATTACH_FILTER
290 SO_BACKLOG
a0d0e21e 291 SO_BROADCAST
7198d2fd 292 SO_CHAMELEON
a0d0e21e 293 SO_DEBUG
7198d2fd
JH
294 SO_DETACH_FILTER
295 SO_DGRAM_ERRIND
a0d0e21e
LW
296 SO_DONTLINGER
297 SO_DONTROUTE
298 SO_ERROR
7198d2fd 299 SO_FAMILY
a0d0e21e
LW
300 SO_KEEPALIVE
301 SO_LINGER
302 SO_OOBINLINE
7198d2fd
JH
303 SO_PASSCRED
304 SO_PASSIFNAME
305 SO_PEERCRED
306 SO_PROTOCOL
307 SO_PROTOTYPE
a0d0e21e
LW
308 SO_RCVBUF
309 SO_RCVLOWAT
310 SO_RCVTIMEO
311 SO_REUSEADDR
b2f54bf3 312 SO_REUSEPORT
7198d2fd
JH
313 SO_SECURITY_AUTHENTICATION
314 SO_SECURITY_ENCRYPTION_NETWORK
315 SO_SECURITY_ENCRYPTION_TRANSPORT
a0d0e21e
LW
316 SO_SNDBUF
317 SO_SNDLOWAT
318 SO_SNDTIMEO
7198d2fd 319 SO_STATE
a0d0e21e
LW
320 SO_TYPE
321 SO_USELOOPBACK
7198d2fd
JH
322 SO_XOPEN
323 SO_XSE
6b1016b5 324 UIO_MAXIOV
a0d0e21e
LW
325);
326
1494e794
JP
327@EXPORT_OK = qw(CR LF CRLF $CR $LF $CRLF
328
329 IPPROTO_TCP
330 TCP_KEEPALIVE
331 TCP_MAXRT
332 TCP_MAXSEG
333 TCP_NODELAY
334 TCP_STDURG);
fdb41d65
CN
335
336%EXPORT_TAGS = (
dde527fc 337 crlf => [qw(CR LF CRLF $CR $LF $CRLF)],
fdb41d65
CN
338 all => [@EXPORT, @EXPORT_OK],
339);
340
341BEGIN {
342 sub CR () {"\015"}
343 sub LF () {"\012"}
344 sub CRLF () {"\015\012"}
345}
346
347*CR = \CR();
348*LF = \LF();
349*CRLF = \CRLF();
350
4633a7c4
LW
351sub sockaddr_in {
352 if (@_ == 6 && !wantarray) { # perl5.001m compat; use this && die
353 my($af, $port, @quad) = @_;
d3a7d8c7
GS
354 warnings::warn "6-ARG sockaddr_in call is deprecated"
355 if warnings::enabled();
4633a7c4
LW
356 pack_sockaddr_in($port, inet_aton(join('.', @quad)));
357 } elsif (wantarray) {
358 croak "usage: (port,iaddr) = sockaddr_in(sin_sv)" unless @_ == 1;
359 unpack_sockaddr_in(@_);
360 } else {
361 croak "usage: sin_sv = sockaddr_in(port,iaddr))" unless @_ == 2;
362 pack_sockaddr_in(@_);
363 }
364}
365
366sub sockaddr_un {
367 if (wantarray) {
368 croak "usage: (filename) = sockaddr_un(sun_sv)" unless @_ == 1;
369 unpack_sockaddr_un(@_);
370 } else {
37120919
AD
371 croak "usage: sun_sv = sockaddr_un(filename)" unless @_ == 1;
372 pack_sockaddr_un(@_);
4633a7c4
LW
373 }
374}
375
a0d0e21e 376sub AUTOLOAD {
73c78b0a 377 my($constname);
a0d0e21e 378 ($constname = $AUTOLOAD) =~ s/.*:://;
b903fcff
JH
379 croak "&Socket::constant not defined" if $constname eq 'constant';
380 my ($error, $val) = constant($constname);
381 if ($error) {
382 croak $error;
a0d0e21e 383 }
cea00dc5 384 *$AUTOLOAD = sub { $val };
a0d0e21e
LW
385 goto &$AUTOLOAD;
386}
387
9426adcd 388XSLoader::load 'Socket', $VERSION;
a0d0e21e 389
a0d0e21e 3901;