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