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