This is a live mirror of the Perl 5 development currently hosted at https://github.com/perl/perl5
perlhist.pod 1.54, containing 5_53.
[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
196 MSG_DONTROUTE
197 MSG_MAXIOVLEN
198 MSG_OOB
199 MSG_PEEK
200 PF_802
201 PF_APPLETALK
202 PF_CCITT
203 PF_CHAOS
204 PF_DATAKIT
205 PF_DECnet
206 PF_DLI
207 PF_ECMA
208 PF_GOSIP
209 PF_HYLINK
210 PF_IMPLINK
211 PF_INET
212 PF_LAT
213 PF_MAX
214 PF_NBS
215 PF_NIT
216 PF_NS
217 PF_OSI
218 PF_OSINET
219 PF_PUP
220 PF_SNA
221 PF_UNIX
222 PF_UNSPEC
223 PF_X25
224 SOCK_DGRAM
225 SOCK_RAW
226 SOCK_RDM
227 SOCK_SEQPACKET
228 SOCK_STREAM
229 SOL_SOCKET
230 SOMAXCONN
231 SO_ACCEPTCONN
232 SO_BROADCAST
233 SO_DEBUG
234 SO_DONTLINGER
235 SO_DONTROUTE
236 SO_ERROR
237 SO_KEEPALIVE
238 SO_LINGER
239 SO_OOBINLINE
240 SO_RCVBUF
241 SO_RCVLOWAT
242 SO_RCVTIMEO
243 SO_REUSEADDR
244 SO_SNDBUF
245 SO_SNDLOWAT
246 SO_SNDTIMEO
247 SO_TYPE
248 SO_USELOOPBACK
249);
250
fdb41d65
CN
251@EXPORT_OK = qw(CR LF CRLF $CR $LF $CRLF);
252
253%EXPORT_TAGS = (
dde527fc 254 crlf => [qw(CR LF CRLF $CR $LF $CRLF)],
fdb41d65
CN
255 all => [@EXPORT, @EXPORT_OK],
256);
257
258BEGIN {
259 sub CR () {"\015"}
260 sub LF () {"\012"}
261 sub CRLF () {"\015\012"}
262}
263
264*CR = \CR();
265*LF = \LF();
266*CRLF = \CRLF();
267
4633a7c4
LW
268sub sockaddr_in {
269 if (@_ == 6 && !wantarray) { # perl5.001m compat; use this && die
270 my($af, $port, @quad) = @_;
271 carp "6-ARG sockaddr_in call is deprecated" if $^W;
272 pack_sockaddr_in($port, inet_aton(join('.', @quad)));
273 } elsif (wantarray) {
274 croak "usage: (port,iaddr) = sockaddr_in(sin_sv)" unless @_ == 1;
275 unpack_sockaddr_in(@_);
276 } else {
277 croak "usage: sin_sv = sockaddr_in(port,iaddr))" unless @_ == 2;
278 pack_sockaddr_in(@_);
279 }
280}
281
282sub sockaddr_un {
283 if (wantarray) {
284 croak "usage: (filename) = sockaddr_un(sun_sv)" unless @_ == 1;
285 unpack_sockaddr_un(@_);
286 } else {
37120919
AD
287 croak "usage: sun_sv = sockaddr_un(filename)" unless @_ == 1;
288 pack_sockaddr_un(@_);
4633a7c4
LW
289 }
290}
291
292
a0d0e21e 293sub AUTOLOAD {
73c78b0a 294 my($constname);
a0d0e21e 295 ($constname = $AUTOLOAD) =~ s/.*:://;
73c78b0a 296 my $val = constant($constname, @_ ? $_[0] : 0);
a0d0e21e 297 if ($! != 0) {
676d8cc7
AK
298 my ($pack,$file,$line) = caller;
299 croak "Your vendor has not defined Socket macro $constname, used";
a0d0e21e
LW
300 }
301 eval "sub $AUTOLOAD { $val }";
302 goto &$AUTOLOAD;
303}
304
73c78b0a 305bootstrap Socket $VERSION;
a0d0e21e 306
a0d0e21e 3071;