This is a live mirror of the Perl 5 development currently hosted at https://github.com/perl/perl5
display more frequent progress messages when STDOUT is a tty
[perl5.git] / ext / Socket / Socket.pm
CommitLineData
a0d0e21e 1package Socket;
73c78b0a 2
fdb41d65
CN
3use vars qw($VERSION @ISA @EXPORT @EXPORT_OK %EXPORT_TAGS);
4$VERSION = "1.7";
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
2ae324a7
PP
59=over
60
8e07c86e
AD
61=item inet_aton HOSTNAME
62
63Takes a string giving the name of a host, and translates that
64to the 4-byte string (structure). Takes arguments of both
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
AD
68
69=item inet_ntoa IP_ADDRESS
70
71Takes a four byte ip address (as returned by inet_aton())
72and translates it into a string of the form 'd.d.d.d'
73where the 'd's are numbers less than 256 (the normal
74readable four dotted number notation for internet addresses).
75
76=item INADDR_ANY
77
4633a7c4 78Note: does not return a number, but a packed string.
8e07c86e
AD
79
80Returns the 4-byte wildcard ip address which specifies any
81of the hosts ip addresses. (A particular machine can have
82more than one ip address, each address corresponding to
83a particular network interface. This wildcard address
84allows you to bind to all of them simultaneously.)
85Normally equivalent to inet_aton('0.0.0.0').
86
7e1af8bc
PP
87=item INADDR_BROADCAST
88
89Note: does not return a number, but a packed string.
90
91Returns the 4-byte 'this-lan' ip broadcast address.
92This can be useful for some protocols to solicit information
93from all servers on the same LAN cable.
94Normally equivalent to inet_aton('255.255.255.255').
95
8e07c86e
AD
96=item INADDR_LOOPBACK
97
98Note - does not return a number.
99
100Returns the 4-byte loopback address. Normally equivalent
101to inet_aton('localhost').
3b35bae3 102
8e07c86e
AD
103=item INADDR_NONE
104
105Note - does not return a number.
106
7e1af8bc 107Returns the 4-byte 'invalid' ip address. Normally equivalent
8e07c86e
AD
108to inet_aton('255.255.255.255').
109
4633a7c4
LW
110=item sockaddr_in PORT, ADDRESS
111
112=item sockaddr_in SOCKADDR_IN
113
114In an array context, unpacks its SOCKADDR_IN argument and returns an array
115consisting of (PORT, ADDRESS). In a scalar context, packs its (PORT,
116ADDRESS) arguments as a SOCKADDR_IN and returns it. If this is confusing,
117use pack_sockaddr_in() and unpack_sockaddr_in() explicitly.
118
119=item pack_sockaddr_in PORT, IP_ADDRESS
8e07c86e 120
4633a7c4
LW
121Takes two arguments, a port number and a 4 byte IP_ADDRESS (as returned by
122inet_aton()). Returns the sockaddr_in structure with those arguments
123packed in with AF_INET filled in. For internet domain sockets, this
124structure is normally what you need for the arguments in bind(),
125connect(), and send(), and is also returned by getpeername(),
126getsockname() and recv().
8e07c86e
AD
127
128=item unpack_sockaddr_in SOCKADDR_IN
129
4633a7c4
LW
130Takes a sockaddr_in structure (as returned by pack_sockaddr_in()) and
131returns an array of two elements: the port and the 4-byte ip-address.
132Will croak if the structure does not have AF_INET in the right place.
133
134=item sockaddr_un PATHNAME
135
136=item sockaddr_un SOCKADDR_UN
137
138In an array context, unpacks its SOCKADDR_UN argument and returns an array
1fef88e7 139consisting of (PATHNAME). In a scalar context, packs its PATHNAME
4633a7c4
LW
140arguments as a SOCKADDR_UN and returns it. If this is confusing, use
141pack_sockaddr_un() and unpack_sockaddr_un() explicitly.
1fef88e7 142These are only supported if your system has E<lt>F<sys/un.h>E<gt>.
4633a7c4
LW
143
144=item pack_sockaddr_un PATH
145
146Takes one argument, a pathname. Returns the sockaddr_un structure with
147that path packed in with AF_UNIX filled in. For unix domain sockets, this
148structure is normally what you need for the arguments in bind(),
149connect(), and send(), and is also returned by getpeername(),
150getsockname() and recv().
151
152=item unpack_sockaddr_un SOCKADDR_UN
153
154Takes a sockaddr_un structure (as returned by pack_sockaddr_un())
155and returns the pathname. Will croak if the structure does not
156have AF_UNIX in the right place.
3b35bae3 157
2ae324a7
PP
158=back
159
3b35bae3
AD
160=cut
161
a0d0e21e
LW
162use Carp;
163
164require Exporter;
a0d0e21e 165require DynaLoader;
fec02dd3 166@ISA = qw(Exporter DynaLoader);
a0d0e21e 167@EXPORT = qw(
8e07c86e 168 inet_aton inet_ntoa pack_sockaddr_in unpack_sockaddr_in
4633a7c4
LW
169 pack_sockaddr_un unpack_sockaddr_un
170 sockaddr_in sockaddr_un
7e1af8bc 171 INADDR_ANY INADDR_BROADCAST INADDR_LOOPBACK INADDR_NONE
a0d0e21e
LW
172 AF_802
173 AF_APPLETALK
174 AF_CCITT
175 AF_CHAOS
176 AF_DATAKIT
177 AF_DECnet
178 AF_DLI
179 AF_ECMA
180 AF_GOSIP
181 AF_HYLINK
182 AF_IMPLINK
183 AF_INET
184 AF_LAT
185 AF_MAX
186 AF_NBS
187 AF_NIT
188 AF_NS
189 AF_OSI
190 AF_OSINET
191 AF_PUP
192 AF_SNA
193 AF_UNIX
194 AF_UNSPEC
195 AF_X25
6b1016b5
JH
196 IOV_MAX
197 MSG_BCAST
de4597cb
JH
198 MSG_CTLFLAGS
199 MSG_CTLIGNORE
200 MSG_CTRUNC
a0d0e21e 201 MSG_DONTROUTE
de4597cb
JH
202 MSG_DONTWAIT
203 MSG_EOF
204 MSG_EOR
205 MSG_ERRQUEUE
206 MSG_FIN
a0d0e21e 207 MSG_MAXIOVLEN
6b1016b5 208 MSG_MCAST
de4597cb 209 MSG_NOSIGNAL
a0d0e21e
LW
210 MSG_OOB
211 MSG_PEEK
de4597cb
JH
212 MSG_PROXY
213 MSG_RST
214 MSG_SYN
215 MSG_TRUNC
216 MSG_URG
217 MSG_WAITALL
a0d0e21e
LW
218 PF_802
219 PF_APPLETALK
220 PF_CCITT
221 PF_CHAOS
222 PF_DATAKIT
223 PF_DECnet
224 PF_DLI
225 PF_ECMA
226 PF_GOSIP
227 PF_HYLINK
228 PF_IMPLINK
229 PF_INET
230 PF_LAT
231 PF_MAX
232 PF_NBS
233 PF_NIT
234 PF_NS
235 PF_OSI
236 PF_OSINET
237 PF_PUP
238 PF_SNA
239 PF_UNIX
240 PF_UNSPEC
241 PF_X25
de4597cb
JH
242 SCM_CONNECT
243 SCM_CREDENTIALS
244 SCM_CREDS
245 SCM_RIGHTS
246 SCM_TIMESTAMP
a0d0e21e
LW
247 SOCK_DGRAM
248 SOCK_RAW
249 SOCK_RDM
250 SOCK_SEQPACKET
251 SOCK_STREAM
252 SOL_SOCKET
253 SOMAXCONN
254 SO_ACCEPTCONN
255 SO_BROADCAST
256 SO_DEBUG
257 SO_DONTLINGER
258 SO_DONTROUTE
259 SO_ERROR
260 SO_KEEPALIVE
261 SO_LINGER
262 SO_OOBINLINE
263 SO_RCVBUF
264 SO_RCVLOWAT
265 SO_RCVTIMEO
266 SO_REUSEADDR
267 SO_SNDBUF
268 SO_SNDLOWAT
269 SO_SNDTIMEO
270 SO_TYPE
271 SO_USELOOPBACK
6b1016b5 272 UIO_MAXIOV
a0d0e21e
LW
273);
274
fdb41d65
CN
275@EXPORT_OK = qw(CR LF CRLF $CR $LF $CRLF);
276
277%EXPORT_TAGS = (
dde527fc 278 crlf => [qw(CR LF CRLF $CR $LF $CRLF)],
fdb41d65
CN
279 all => [@EXPORT, @EXPORT_OK],
280);
281
282BEGIN {
283 sub CR () {"\015"}
284 sub LF () {"\012"}
285 sub CRLF () {"\015\012"}
286}
287
288*CR = \CR();
289*LF = \LF();
290*CRLF = \CRLF();
291
4633a7c4
LW
292sub sockaddr_in {
293 if (@_ == 6 && !wantarray) { # perl5.001m compat; use this && die
294 my($af, $port, @quad) = @_;
295 carp "6-ARG sockaddr_in call is deprecated" if $^W;
296 pack_sockaddr_in($port, inet_aton(join('.', @quad)));
297 } elsif (wantarray) {
298 croak "usage: (port,iaddr) = sockaddr_in(sin_sv)" unless @_ == 1;
299 unpack_sockaddr_in(@_);
300 } else {
301 croak "usage: sin_sv = sockaddr_in(port,iaddr))" unless @_ == 2;
302 pack_sockaddr_in(@_);
303 }
304}
305
306sub sockaddr_un {
307 if (wantarray) {
308 croak "usage: (filename) = sockaddr_un(sun_sv)" unless @_ == 1;
309 unpack_sockaddr_un(@_);
310 } else {
37120919
AD
311 croak "usage: sun_sv = sockaddr_un(filename)" unless @_ == 1;
312 pack_sockaddr_un(@_);
4633a7c4
LW
313 }
314}
315
316
a0d0e21e 317sub AUTOLOAD {
73c78b0a 318 my($constname);
a0d0e21e 319 ($constname = $AUTOLOAD) =~ s/.*:://;
73c78b0a 320 my $val = constant($constname, @_ ? $_[0] : 0);
a0d0e21e 321 if ($! != 0) {
676d8cc7
AK
322 my ($pack,$file,$line) = caller;
323 croak "Your vendor has not defined Socket macro $constname, used";
a0d0e21e
LW
324 }
325 eval "sub $AUTOLOAD { $val }";
326 goto &$AUTOLOAD;
327}
328
73c78b0a 329bootstrap Socket $VERSION;
a0d0e21e 330
a0d0e21e 3311;