This is a live mirror of the Perl 5 development currently hosted at https://github.com/perl/perl5
(replaced by #13395)
[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
LW
180 AF_802
181 AF_APPLETALK
182 AF_CCITT
183 AF_CHAOS
184 AF_DATAKIT
185 AF_DECnet
186 AF_DLI
187 AF_ECMA
188 AF_GOSIP
189 AF_HYLINK
190 AF_IMPLINK
191 AF_INET
192 AF_LAT
193 AF_MAX
194 AF_NBS
195 AF_NIT
196 AF_NS
197 AF_OSI
198 AF_OSINET
199 AF_PUP
200 AF_SNA
201 AF_UNIX
202 AF_UNSPEC
203 AF_X25
6b1016b5
JH
204 IOV_MAX
205 MSG_BCAST
de4597cb
JH
206 MSG_CTLFLAGS
207 MSG_CTLIGNORE
208 MSG_CTRUNC
a0d0e21e 209 MSG_DONTROUTE
de4597cb
JH
210 MSG_DONTWAIT
211 MSG_EOF
212 MSG_EOR
213 MSG_ERRQUEUE
214 MSG_FIN
a0d0e21e 215 MSG_MAXIOVLEN
6b1016b5 216 MSG_MCAST
de4597cb 217 MSG_NOSIGNAL
a0d0e21e
LW
218 MSG_OOB
219 MSG_PEEK
de4597cb
JH
220 MSG_PROXY
221 MSG_RST
222 MSG_SYN
223 MSG_TRUNC
224 MSG_URG
225 MSG_WAITALL
a0d0e21e
LW
226 PF_802
227 PF_APPLETALK
228 PF_CCITT
229 PF_CHAOS
230 PF_DATAKIT
231 PF_DECnet
232 PF_DLI
233 PF_ECMA
234 PF_GOSIP
235 PF_HYLINK
236 PF_IMPLINK
237 PF_INET
238 PF_LAT
239 PF_MAX
240 PF_NBS
241 PF_NIT
242 PF_NS
243 PF_OSI
244 PF_OSINET
245 PF_PUP
246 PF_SNA
247 PF_UNIX
248 PF_UNSPEC
249 PF_X25
de4597cb
JH
250 SCM_CONNECT
251 SCM_CREDENTIALS
252 SCM_CREDS
253 SCM_RIGHTS
254 SCM_TIMESTAMP
ca6e1c26
JH
255 SHUT_RD
256 SHUT_RDWR
257 SHUT_WR
a0d0e21e
LW
258 SOCK_DGRAM
259 SOCK_RAW
260 SOCK_RDM
261 SOCK_SEQPACKET
262 SOCK_STREAM
263 SOL_SOCKET
264 SOMAXCONN
265 SO_ACCEPTCONN
266 SO_BROADCAST
267 SO_DEBUG
268 SO_DONTLINGER
269 SO_DONTROUTE
270 SO_ERROR
271 SO_KEEPALIVE
272 SO_LINGER
273 SO_OOBINLINE
274 SO_RCVBUF
275 SO_RCVLOWAT
276 SO_RCVTIMEO
277 SO_REUSEADDR
b2f54bf3 278 SO_REUSEPORT
a0d0e21e
LW
279 SO_SNDBUF
280 SO_SNDLOWAT
281 SO_SNDTIMEO
282 SO_TYPE
283 SO_USELOOPBACK
6b1016b5 284 UIO_MAXIOV
a0d0e21e
LW
285);
286
1494e794
JP
287@EXPORT_OK = qw(CR LF CRLF $CR $LF $CRLF
288
289 IPPROTO_TCP
290 TCP_KEEPALIVE
291 TCP_MAXRT
292 TCP_MAXSEG
293 TCP_NODELAY
294 TCP_STDURG);
fdb41d65
CN
295
296%EXPORT_TAGS = (
dde527fc 297 crlf => [qw(CR LF CRLF $CR $LF $CRLF)],
fdb41d65
CN
298 all => [@EXPORT, @EXPORT_OK],
299);
300
301BEGIN {
302 sub CR () {"\015"}
303 sub LF () {"\012"}
304 sub CRLF () {"\015\012"}
305}
306
307*CR = \CR();
308*LF = \LF();
309*CRLF = \CRLF();
310
4633a7c4
LW
311sub sockaddr_in {
312 if (@_ == 6 && !wantarray) { # perl5.001m compat; use this && die
313 my($af, $port, @quad) = @_;
d3a7d8c7
GS
314 warnings::warn "6-ARG sockaddr_in call is deprecated"
315 if warnings::enabled();
4633a7c4
LW
316 pack_sockaddr_in($port, inet_aton(join('.', @quad)));
317 } elsif (wantarray) {
318 croak "usage: (port,iaddr) = sockaddr_in(sin_sv)" unless @_ == 1;
319 unpack_sockaddr_in(@_);
320 } else {
321 croak "usage: sin_sv = sockaddr_in(port,iaddr))" unless @_ == 2;
322 pack_sockaddr_in(@_);
323 }
324}
325
326sub sockaddr_un {
327 if (wantarray) {
328 croak "usage: (filename) = sockaddr_un(sun_sv)" unless @_ == 1;
329 unpack_sockaddr_un(@_);
330 } else {
37120919
AD
331 croak "usage: sun_sv = sockaddr_un(filename)" unless @_ == 1;
332 pack_sockaddr_un(@_);
4633a7c4
LW
333 }
334}
335
a0d0e21e 336sub AUTOLOAD {
73c78b0a 337 my($constname);
a0d0e21e 338 ($constname = $AUTOLOAD) =~ s/.*:://;
b903fcff
JH
339 croak "&Socket::constant not defined" if $constname eq 'constant';
340 my ($error, $val) = constant($constname);
341 if ($error) {
342 croak $error;
a0d0e21e 343 }
cea00dc5 344 *$AUTOLOAD = sub { $val };
a0d0e21e
LW
345 goto &$AUTOLOAD;
346}
347
9426adcd 348XSLoader::load 'Socket', $VERSION;
a0d0e21e 349
a0d0e21e 3501;