This is a live mirror of the Perl 5 development currently hosted at https://github.com/perl/perl5
[REPATCH] Re: [PATCH] new test lib/blib.t
[perl5.git] / ext / Socket / Socket.pm
CommitLineData
a0d0e21e 1package Socket;
73c78b0a 2
17f410f9 3our($VERSION, @ISA, @EXPORT, @EXPORT_OK, %EXPORT_TAGS);
cea00dc5 4$VERSION = "1.74";
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
63Takes a string giving the name of a host, and translates that
2528d3bc 64to an opaque string (struct in_adrr). Takes arguments of both
8e07c86e 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 68
2528d3bc
JH
69For portability do not assume that the result of inet_aton() is 32
70bits wide, that it would contain only the IPv4 address in network
71order.
72
8e07c86e
AD
73=item inet_ntoa IP_ADDRESS
74
2528d3bc
JH
75Takes a string (an opaque string as returned by inet_aton(), or
76a v-string representing the four octets of the IPv4 address in
77network order) and translates it into a string of the form 'd.d.d.d'
78where the 'd's are numbers less than 256 (the normal readable four
79dotted 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
86of the hosts ip addresses. (A particular machine can have
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
105Returns the 4-byte loopback address. Normally equivalent
106to inet_aton('localhost').
3b35bae3 107
8e07c86e
AD
108=item INADDR_NONE
109
110Note - does not return a number.
111
7e1af8bc 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
4633a7c4
LW
126Takes two arguments, a port number and a 4 byte IP_ADDRESS (as returned by
127inet_aton()). Returns the sockaddr_in structure with those arguments
128packed in with AF_INET filled in. For internet domain sockets, this
129structure is normally what you need for the arguments in bind(),
130connect(), and send(), and is also returned by getpeername(),
131getsockname() and recv().
8e07c86e
AD
132
133=item unpack_sockaddr_in SOCKADDR_IN
134
4633a7c4
LW
135Takes a sockaddr_in structure (as returned by pack_sockaddr_in()) and
136returns an array of two elements: the port and the 4-byte ip-address.
137Will croak if the structure does not have AF_INET in the right place.
138
139=item sockaddr_un PATHNAME
140
141=item sockaddr_un SOCKADDR_UN
142
91e74348 143In a list context, unpacks its SOCKADDR_UN argument and returns an array
1fef88e7 144consisting of (PATHNAME). In a scalar context, packs its PATHNAME
4633a7c4
LW
145arguments as a SOCKADDR_UN and returns it. If this is confusing, use
146pack_sockaddr_un() and unpack_sockaddr_un() explicitly.
1fef88e7 147These are only supported if your system has E<lt>F<sys/un.h>E<gt>.
4633a7c4
LW
148
149=item pack_sockaddr_un PATH
150
151Takes one argument, a pathname. Returns the sockaddr_un structure with
152that path packed in with AF_UNIX filled in. For unix domain sockets, this
153structure is normally what you need for the arguments in bind(),
154connect(), and send(), and is also returned by getpeername(),
155getsockname() and recv().
156
157=item unpack_sockaddr_un SOCKADDR_UN
158
159Takes a sockaddr_un structure (as returned by pack_sockaddr_un())
160and returns the pathname. Will croak if the structure does not
161have AF_UNIX in the right place.
3b35bae3 162
2ae324a7
PP
163=back
164
3b35bae3
AD
165=cut
166
a0d0e21e 167use Carp;
d3a7d8c7 168use warnings::register;
a0d0e21e
LW
169
170require Exporter;
9426adcd
IZ
171use XSLoader ();
172@ISA = qw(Exporter);
a0d0e21e 173@EXPORT = qw(
8e07c86e 174 inet_aton inet_ntoa pack_sockaddr_in unpack_sockaddr_in
4633a7c4
LW
175 pack_sockaddr_un unpack_sockaddr_un
176 sockaddr_in sockaddr_un
7e1af8bc 177 INADDR_ANY INADDR_BROADCAST INADDR_LOOPBACK INADDR_NONE
a0d0e21e
LW
178 AF_802
179 AF_APPLETALK
180 AF_CCITT
181 AF_CHAOS
182 AF_DATAKIT
183 AF_DECnet
184 AF_DLI
185 AF_ECMA
186 AF_GOSIP
187 AF_HYLINK
188 AF_IMPLINK
189 AF_INET
190 AF_LAT
191 AF_MAX
192 AF_NBS
193 AF_NIT
194 AF_NS
195 AF_OSI
196 AF_OSINET
197 AF_PUP
198 AF_SNA
199 AF_UNIX
200 AF_UNSPEC
201 AF_X25
6b1016b5
JH
202 IOV_MAX
203 MSG_BCAST
de4597cb
JH
204 MSG_CTLFLAGS
205 MSG_CTLIGNORE
206 MSG_CTRUNC
a0d0e21e 207 MSG_DONTROUTE
de4597cb
JH
208 MSG_DONTWAIT
209 MSG_EOF
210 MSG_EOR
211 MSG_ERRQUEUE
212 MSG_FIN
a0d0e21e 213 MSG_MAXIOVLEN
6b1016b5 214 MSG_MCAST
de4597cb 215 MSG_NOSIGNAL
a0d0e21e
LW
216 MSG_OOB
217 MSG_PEEK
de4597cb
JH
218 MSG_PROXY
219 MSG_RST
220 MSG_SYN
221 MSG_TRUNC
222 MSG_URG
223 MSG_WAITALL
a0d0e21e
LW
224 PF_802
225 PF_APPLETALK
226 PF_CCITT
227 PF_CHAOS
228 PF_DATAKIT
229 PF_DECnet
230 PF_DLI
231 PF_ECMA
232 PF_GOSIP
233 PF_HYLINK
234 PF_IMPLINK
235 PF_INET
236 PF_LAT
237 PF_MAX
238 PF_NBS
239 PF_NIT
240 PF_NS
241 PF_OSI
242 PF_OSINET
243 PF_PUP
244 PF_SNA
245 PF_UNIX
246 PF_UNSPEC
247 PF_X25
de4597cb
JH
248 SCM_CONNECT
249 SCM_CREDENTIALS
250 SCM_CREDS
251 SCM_RIGHTS
252 SCM_TIMESTAMP
ca6e1c26
JH
253 SHUT_RD
254 SHUT_RDWR
255 SHUT_WR
a0d0e21e
LW
256 SOCK_DGRAM
257 SOCK_RAW
258 SOCK_RDM
259 SOCK_SEQPACKET
260 SOCK_STREAM
261 SOL_SOCKET
262 SOMAXCONN
263 SO_ACCEPTCONN
264 SO_BROADCAST
265 SO_DEBUG
266 SO_DONTLINGER
267 SO_DONTROUTE
268 SO_ERROR
269 SO_KEEPALIVE
270 SO_LINGER
271 SO_OOBINLINE
272 SO_RCVBUF
273 SO_RCVLOWAT
274 SO_RCVTIMEO
275 SO_REUSEADDR
b2f54bf3 276 SO_REUSEPORT
a0d0e21e
LW
277 SO_SNDBUF
278 SO_SNDLOWAT
279 SO_SNDTIMEO
280 SO_TYPE
281 SO_USELOOPBACK
6b1016b5 282 UIO_MAXIOV
a0d0e21e
LW
283);
284
1494e794
JP
285@EXPORT_OK = qw(CR LF CRLF $CR $LF $CRLF
286
287 IPPROTO_TCP
288 TCP_KEEPALIVE
289 TCP_MAXRT
290 TCP_MAXSEG
291 TCP_NODELAY
292 TCP_STDURG);
fdb41d65
CN
293
294%EXPORT_TAGS = (
dde527fc 295 crlf => [qw(CR LF CRLF $CR $LF $CRLF)],
fdb41d65
CN
296 all => [@EXPORT, @EXPORT_OK],
297);
298
299BEGIN {
300 sub CR () {"\015"}
301 sub LF () {"\012"}
302 sub CRLF () {"\015\012"}
303}
304
305*CR = \CR();
306*LF = \LF();
307*CRLF = \CRLF();
308
4633a7c4
LW
309sub sockaddr_in {
310 if (@_ == 6 && !wantarray) { # perl5.001m compat; use this && die
311 my($af, $port, @quad) = @_;
d3a7d8c7
GS
312 warnings::warn "6-ARG sockaddr_in call is deprecated"
313 if warnings::enabled();
4633a7c4
LW
314 pack_sockaddr_in($port, inet_aton(join('.', @quad)));
315 } elsif (wantarray) {
316 croak "usage: (port,iaddr) = sockaddr_in(sin_sv)" unless @_ == 1;
317 unpack_sockaddr_in(@_);
318 } else {
319 croak "usage: sin_sv = sockaddr_in(port,iaddr))" unless @_ == 2;
320 pack_sockaddr_in(@_);
321 }
322}
323
324sub sockaddr_un {
325 if (wantarray) {
326 croak "usage: (filename) = sockaddr_un(sun_sv)" unless @_ == 1;
327 unpack_sockaddr_un(@_);
328 } else {
37120919
AD
329 croak "usage: sun_sv = sockaddr_un(filename)" unless @_ == 1;
330 pack_sockaddr_un(@_);
4633a7c4
LW
331 }
332}
333
a0d0e21e 334sub AUTOLOAD {
73c78b0a 335 my($constname);
a0d0e21e 336 ($constname = $AUTOLOAD) =~ s/.*:://;
b903fcff
JH
337 croak "&Socket::constant not defined" if $constname eq 'constant';
338 my ($error, $val) = constant($constname);
339 if ($error) {
340 croak $error;
a0d0e21e 341 }
cea00dc5 342 *$AUTOLOAD = sub { $val };
a0d0e21e
LW
343 goto &$AUTOLOAD;
344}
345
9426adcd 346XSLoader::load 'Socket', $VERSION;
a0d0e21e 347
a0d0e21e 3481;