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
1 package Socket;
2
3 use vars qw($VERSION @ISA @EXPORT);
4 $VERSION = "1.6";
5
6 =head1 NAME
7
8 Socket, sockaddr_in, sockaddr_un, inet_aton, inet_ntoa - load the C socket.h defines and structure manipulators 
9
10 =head1 SYNOPSIS
11
12     use Socket;
13
14     $proto = getprotobyname('udp');
15     socket(Socket_Handle, PF_INET, SOCK_DGRAM, $proto);
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);
38
39 =head1 DESCRIPTION
40
41 This module is just a translation of the C F<socket.h> file.
42 Unlike the old mechanism of requiring a translated F<socket.ph>
43 file, this uses the B<h2xs> program (see the Perl source distribution)
44 and your native C compiler.  This means that it has a 
45 far more likely chance of getting the numbers right.  This includes
46 all of the commonly used pound-defines like AF_INET, SOCK_STREAM, etc.
47
48 In addition, some structure manipulation functions are available:
49
50 =over
51
52 =item inet_aton HOSTNAME
53
54 Takes a string giving the name of a host, and translates that
55 to the 4-byte string (structure). Takes arguments of both
56 the 'rtfm.mit.edu' type and '18.181.0.24'. If the host name
57 cannot be resolved, returns undef. For multi-homed hosts (hosts
58 with more than one address), the first address found is returned.
59
60 =item inet_ntoa IP_ADDRESS
61
62 Takes a four byte ip address (as returned by inet_aton())
63 and translates it into a string of the form 'd.d.d.d'
64 where the 'd's are numbers less than 256 (the normal
65 readable four dotted number notation for internet addresses).
66
67 =item INADDR_ANY
68
69 Note: does not return a number, but a packed string.
70
71 Returns the 4-byte wildcard ip address which specifies any
72 of the hosts ip addresses. (A particular machine can have
73 more than one ip address, each address corresponding to
74 a particular network interface. This wildcard address
75 allows you to bind to all of them simultaneously.)
76 Normally equivalent to inet_aton('0.0.0.0').
77
78 =item INADDR_BROADCAST
79
80 Note: does not return a number, but a packed string.
81
82 Returns the 4-byte 'this-lan' ip broadcast address.
83 This can be useful for some protocols to solicit information
84 from all servers on the same LAN cable.
85 Normally equivalent to inet_aton('255.255.255.255').
86
87 =item INADDR_LOOPBACK
88
89 Note - does not return a number.
90
91 Returns the 4-byte loopback address. Normally equivalent
92 to inet_aton('localhost').
93
94 =item INADDR_NONE
95
96 Note - does not return a number.
97
98 Returns the 4-byte 'invalid' ip address. Normally equivalent
99 to inet_aton('255.255.255.255').
100
101 =item sockaddr_in PORT, ADDRESS
102
103 =item sockaddr_in SOCKADDR_IN
104
105 In an array context, unpacks its SOCKADDR_IN argument and returns an array
106 consisting of (PORT, ADDRESS).  In a scalar context, packs its (PORT,
107 ADDRESS) arguments as a SOCKADDR_IN and returns it.  If this is confusing,
108 use pack_sockaddr_in() and unpack_sockaddr_in() explicitly.
109
110 =item pack_sockaddr_in PORT, IP_ADDRESS
111
112 Takes two arguments, a port number and a 4 byte IP_ADDRESS (as returned by
113 inet_aton()). Returns the sockaddr_in structure with those arguments
114 packed in with AF_INET filled in.  For internet domain sockets, this
115 structure is normally what you need for the arguments in bind(),
116 connect(), and send(), and is also returned by getpeername(),
117 getsockname() and recv().
118
119 =item unpack_sockaddr_in SOCKADDR_IN
120
121 Takes a sockaddr_in structure (as returned by pack_sockaddr_in()) and
122 returns an array of two elements: the port and the 4-byte ip-address.
123 Will 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
129 In an array context, unpacks its SOCKADDR_UN argument and returns an array
130 consisting of (PATHNAME).  In a scalar context, packs its PATHNAME
131 arguments as a SOCKADDR_UN and returns it.  If this is confusing, use
132 pack_sockaddr_un() and unpack_sockaddr_un() explicitly.
133 These are only supported if your system has E<lt>F<sys/un.h>E<gt>.
134
135 =item pack_sockaddr_un PATH
136
137 Takes one argument, a pathname. Returns the sockaddr_un structure with
138 that path packed in with AF_UNIX filled in. For unix domain sockets, this
139 structure is normally what you need for the arguments in bind(),
140 connect(), and send(), and is also returned by getpeername(),
141 getsockname() and recv().
142
143 =item unpack_sockaddr_un SOCKADDR_UN
144
145 Takes a sockaddr_un structure (as returned by pack_sockaddr_un())
146 and returns the pathname.  Will croak if the structure does not
147 have AF_UNIX in the right place.
148
149 =back
150
151 =cut
152
153 use Carp;
154
155 require Exporter;
156 require DynaLoader;
157 @ISA = qw(Exporter DynaLoader);
158 @EXPORT = qw(
159         inet_aton inet_ntoa pack_sockaddr_in unpack_sockaddr_in
160         pack_sockaddr_un unpack_sockaddr_un
161         sockaddr_in sockaddr_un
162         INADDR_ANY INADDR_BROADCAST INADDR_LOOPBACK INADDR_NONE
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
242 sub 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
256 sub sockaddr_un {
257     if (wantarray) {
258         croak "usage:   (filename) = sockaddr_un(sun_sv)" unless @_ == 1;
259         unpack_sockaddr_un(@_);
260     } else {
261         croak "usage:   sun_sv = sockaddr_un(filename)" unless @_ == 1;
262         pack_sockaddr_un(@_);
263     }
264 }
265
266
267 sub AUTOLOAD {
268     my($constname);
269     ($constname = $AUTOLOAD) =~ s/.*:://;
270     my $val = constant($constname, @_ ? $_[0] : 0);
271     if ($! != 0) {
272         my ($pack,$file,$line) = caller;
273         croak "Your vendor has not defined Socket macro $constname, used";
274     }
275     eval "sub $AUTOLOAD { $val }";
276     goto &$AUTOLOAD;
277 }
278
279 bootstrap Socket $VERSION;
280
281 1;