Debian Codegraph @

upstream/debian-unstable/man3/IO::Socket.3perl

raw
1 .\" -*- mode: troff; coding: utf-8 -*-
2 .\" Automatically generated by Pod::Man 5.0102 (Pod::Simple 3.45)
3 .\"
4 .\" Standard preamble:
5 .\" ========================================================================
6 .de Sp \" Vertical space (when we can't use .PP)
7 .if t .sp .5v
8 .if n .sp
9 ..
10 .de Vb \" Begin verbatim text
11 .ft CW
12 .nf
13 .ne \\$1
14 ..
15 .de Ve \" End verbatim text
16 .ft R
17 .fi
18 ..
19 .\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>.
20 .ie n \{\
21 . ds C` ""
22 . ds C' ""
23 'br\}
24 .el\{\
25 . ds C`
26 . ds C'
27 'br\}
28 .\"
29 .\" Escape single quotes in literal strings from groff's Unicode transform.
30 .ie \n(.g .ds Aq \(aq
31 .el .ds Aq '
32 .\"
33 .\" If the F register is >0, we'll generate index entries on stderr for
34 .\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
35 .\" entries marked with X<> in POD. Of course, you'll have to process the
36 .\" output yourself in some meaningful fashion.
37 .\"
38 .\" Avoid warning from groff about undefined register 'F'.
39 .de IX
40 ..
41 .nr rF 0
42 .if \n(.g .if rF .nr rF 1
43 .if (\n(rF:(\n(.g==0)) \{\
44 . if \nF \{\
45 . de IX
46 . tm Index:\\$1\t\\n%\t"\\$2"
47 ..
48 . if !\nF==2 \{\
49 . nr % 0
50 . nr F 2
51 . \}
52 . \}
53 .\}
54 .rr rF
55 .\" ========================================================================
56 .\"
57 .IX Title "IO::Socket 3perl"
58 .TH IO::Socket 3perl 2025-11-16 "perl v5.40.1" "Perl Programmers Reference Guide"
59 .\" For nroff, turn off justification. Always turn off hyphenation; it makes
60 .\" way too many mistakes in technical documents.
61 .if n .ad l
62 .nh
63 .SH NAME
64 IO::Socket \- Object interface to socket communications
65 .SH SYNOPSIS
66 .IX Header "SYNOPSIS"
67 .Vb 2
68 \& use strict;
69 \& use warnings;
70 \&
71 \& use IO::Socket qw(AF_INET AF_UNIX);
72 \&
73 \& # create a new AF_INET socket
74 \& my $sock = IO::Socket\->new(Domain => AF_INET);
75 \& # which is the same as
76 \& $sock = IO::Socket::INET\->new();
77 \&
78 \& # create a new AF_UNIX socket
79 \& $sock = IO::Socket\->new(Domain => AF_UNIX);
80 \& # which is the same as
81 \& $sock = IO::Socket::UNIX\->new();
82 .Ve
83 .SH DESCRIPTION
84 .IX Header "DESCRIPTION"
85 \&\f(CW\*(C`IO::Socket\*(C'\fR provides an object-oriented, IO::Handle\-based interface to
86 creating and using sockets via Socket, which provides a near one-to-one
87 interface to the C socket library.
88 .PP
89 \&\f(CW\*(C`IO::Socket\*(C'\fR is a base class that really only defines methods for those
90 operations which are common to all types of sockets. Operations which are
91 specific to a particular socket domain have methods defined in subclasses of
92 \&\f(CW\*(C`IO::Socket\*(C'\fR. See IO::Socket::INET, IO::Socket::UNIX, and
93 IO::Socket::IP for examples of such a subclass.
94 .PP
95 \&\f(CW\*(C`IO::Socket\*(C'\fR will export all functions (and constants) defined by Socket.
96 .SH "CONSTRUCTOR ARGUMENTS"
97 .IX Header "CONSTRUCTOR ARGUMENTS"
98 Given that \f(CW\*(C`IO::Socket\*(C'\fR doesn't have attributes in the traditional sense, the
99 following arguments, rather than attributes, can be passed into the
100 constructor.
101 .PP
102 Constructor arguments should be passed in \f(CW\*(C`Key => \*(AqValue\*(Aq\*(C'\fR pairs.
103 .PP
104 The only required argument is "Domain" in IO::Socket.
105 .SS Blocking
106 .IX Subsection "Blocking"
107 .Vb 2
108 \& my $sock = IO::Socket\->new(..., Blocking => 1);
109 \& $sock = IO::Socket\->new(..., Blocking => 0);
110 .Ve
111 .PP
112 If defined but false, the socket will be set to non-blocking mode. If not
113 specified it defaults to \f(CW1\fR (blocking mode).
114 .SS Domain
115 .IX Subsection "Domain"
116 .Vb 2
117 \& my $sock = IO::Socket\->new(Domain => IO::Socket::AF_INET);
118 \& $sock = IO::Socket\->new(Domain => IO::Socket::AF_UNIX);
119 .Ve
120 .PP
121 The socket domain will define which subclass of \f(CW\*(C`IO::Socket\*(C'\fR to use. The two
122 options available along with this distribution are \f(CW\*(C`AF_INET\*(C'\fR and \f(CW\*(C`AF_UNIX\*(C'\fR.
123 .PP
124 \&\f(CW\*(C`AF_INET\*(C'\fR is for the internet address family of sockets and is handled via
125 IO::Socket::INET. \f(CW\*(C`AF_INET\*(C'\fR sockets are bound to an internet address and
126 port.
127 .PP
128 \&\f(CW\*(C`AF_UNIX\*(C'\fR is for the unix domain socket and is handled via
129 IO::Socket::UNIX. \f(CW\*(C`AF_UNIX\*(C'\fR sockets are bound to the file system as their
130 address name space.
131 .PP
132 This argument is \fBrequired\fR. All other arguments are optional.
133 .SS Listen
134 .IX Subsection "Listen"
135 .Vb 1
136 \& my $sock = IO::Socket\->new(..., Listen => 5);
137 .Ve
138 .PP
139 Listen should be an integer value or left unset.
140 .PP
141 If provided, this argument will place the socket into listening mode. New
142 connections can then be accepted using the "accept" in IO::Socket method. The
143 value given is used as the \f(CWlisten(2)\fR queue size.
144 .PP
145 If the \f(CW\*(C`Listen\*(C'\fR argument is given, but false, the queue size will be set to
146 5.
147 .SS Timeout
148 .IX Subsection "Timeout"
149 .Vb 1
150 \& my $sock = IO::Socket\->new(..., Timeout => 5);
151 .Ve
152 .PP
153 The timeout value, in seconds, for this socket connection. How exactly this
154 value is utilized is defined in the socket domain subclasses that make use of
155 the value.
156 .SS Type
157 .IX Subsection "Type"
158 .Vb 1
159 \& my $sock = IO::Socket\->new(..., Type => IO::Socket::SOCK_STREAM);
160 .Ve
161 .PP
162 The socket type that will be used. These are usually \f(CW\*(C`SOCK_STREAM\*(C'\fR,
163 \&\f(CW\*(C`SOCK_DGRAM\*(C'\fR, or \f(CW\*(C`SOCK_RAW\*(C'\fR. If this argument is left undefined an attempt
164 will be made to infer the type from the service name.
165 .PP
166 For example, you'll usually use \f(CW\*(C`SOCK_STREAM\*(C'\fR with a \f(CW\*(C`tcp\*(C'\fR connection and
167 \&\f(CW\*(C`SOCK_DGRAM\*(C'\fR with a \f(CW\*(C`udp\*(C'\fR connection.
168 .SH CONSTRUCTORS
169 .IX Header "CONSTRUCTORS"
170 \&\f(CW\*(C`IO::Socket\*(C'\fR extends the IO::Handle constructor.
171 .SS new
172 .IX Subsection "new"
173 .Vb 1
174 \& my $sock = IO::Socket\->new();
175 \&
176 \& # get a new IO::Socket::INET instance
177 \& $sock = IO::Socket\->new(Domain => IO::Socket::AF_INET);
178 \& # get a new IO::Socket::UNIX instance
179 \& $sock = IO::Socket\->new(Domain => IO::Socket::AF_UNIX);
180 \&
181 \& # Domain is the only required argument
182 \& $sock = IO::Socket\->new(
183 \& Domain => IO::Socket::AF_INET, # AF_INET, AF_UNIX
184 \& Type => IO::Socket::SOCK_STREAM, # SOCK_STREAM, SOCK_DGRAM, ...
185 \& Proto => \*(Aqtcp\*(Aq, # \*(Aqtcp\*(Aq, \*(Aqudp\*(Aq, IPPROTO_TCP, IPPROTO_UDP
186 \& # and so on...
187 \& );
188 .Ve
189 .PP
190 Creates an \f(CW\*(C`IO::Socket\*(C'\fR, which is a reference to a newly created symbol (see
191 the Symbol package). \f(CW\*(C`new\*(C'\fR optionally takes arguments, these arguments
192 are defined in "CONSTRUCTOR ARGUMENTS" in IO::Socket.
193 .PP
194 Any of the "CONSTRUCTOR ARGUMENTS" in IO::Socket may be passed to the
195 constructor, but if any arguments are provided, then one of them must be
196 the "Domain" in IO::Socket argument. The "Domain" in IO::Socket argument can,
197 by default, be either \f(CW\*(C`AF_INET\*(C'\fR or \f(CW\*(C`AF_UNIX\*(C'\fR. Other domains can be used if a
198 proper subclass for the domain family is registered. All other arguments will
199 be passed to the \f(CW\*(C`configuration\*(C'\fR method of the package for that domain.
200 .PP
201 If the constructor fails it will return \f(CW\*(C`undef\*(C'\fR and set the \f(CW$errstr\fR package
202 variable to contain an error message.
203 .PP
204 .Vb 2
205 \& $sock = IO::Socket\->new(...)
206 \& or die "Cannot create socket \- $IO::Socket::errstr\en";
207 .Ve
208 .PP
209 For legacy reasons the error message is also set into the global \f(CW$@\fR
210 variable, and you may still find older code which looks here instead.
211 .PP
212 .Vb 2
213 \& $sock = IO::Socket\->new(...)
214 \& or die "Cannot create socket \- $@\en";
215 .Ve
216 .SH METHODS
217 .IX Header "METHODS"
218 \&\f(CW\*(C`IO::Socket\*(C'\fR inherits all methods from IO::Handle and implements the
219 following new ones.
220 .SS accept
221 .IX Subsection "accept"
222 .Vb 2
223 \& my $client_sock = $sock\->accept();
224 \& my $inet_sock = $sock\->accept(\*(AqIO::Socket::INET\*(Aq);
225 .Ve
226 .PP
227 The accept method will perform the system call \f(CW\*(C`accept\*(C'\fR on the socket and
228 return a new object. The new object will be created in the same class as the
229 listen socket, unless a specific package name is specified. This object can be
230 used to communicate with the client that was trying to connect.
231 .PP
232 This differs slightly from the \f(CW\*(C`accept\*(C'\fR function in perlfunc.
233 .PP
234 In a scalar context the new socket is returned, or \f(CW\*(C`undef\*(C'\fR upon
235 failure. In a list context a two-element array is returned containing
236 the new socket and the peer address; the list will be empty upon failure.
237 .SS atmark
238 .IX Subsection "atmark"
239 .Vb 4
240 \& my $integer = $sock\->atmark();
241 \& # read in some data on a given socket
242 \& my $data;
243 \& $sock\->read($data, 1024) until $sock\->atmark;
244 \&
245 \& # or, export the function to use:
246 \& use IO::Socket \*(Aqsockatmark\*(Aq;
247 \& $sock\->read($data, 1024) until sockatmark($sock);
248 .Ve
249 .PP
250 True if the socket is currently positioned at the urgent data mark, false
251 otherwise. If your system doesn't yet implement \f(CW\*(C`sockatmark\*(C'\fR this will throw
252 an exception.
253 .PP
254 If your system does not support \f(CW\*(C`sockatmark\*(C'\fR, the \f(CW\*(C`use\*(C'\fR declaration will
255 fail at compile time.
256 .SS autoflush
257 .IX Subsection "autoflush"
258 .Vb 6
259 \& # by default, autoflush will be turned on when referenced
260 \& $sock\->autoflush(); # turns on autoflush
261 \& # turn off autoflush
262 \& $sock\->autoflush(0);
263 \& # turn on autoflush
264 \& $sock\->autoflush(1);
265 .Ve
266 .PP
267 This attribute isn't overridden from IO::Handle's implementation. However,
268 since we turn it on by default, it's worth mentioning here.
269 .SS bind
270 .IX Subsection "bind"
271 .Vb 5
272 \& use Socket qw(pack_sockaddr_in);
273 \& my $port = 3000;
274 \& my $ip_address = \*(Aq0.0.0.0\*(Aq;
275 \& my $packed_addr = pack_sockaddr_in($port, $ip_address);
276 \& $sock\->bind($packed_addr);
277 .Ve
278 .PP
279 Binds a network address to a socket, just as \f(CWbind(2)\fR does. Returns true if
280 it succeeded, false otherwise. You should provide a packed address of the
281 appropriate type for the socket.
282 .SS connected
283 .IX Subsection "connected"
284 .Vb 4
285 \& my $peer_addr = $sock\->connected();
286 \& if ($peer_addr) {
287 \& say "We\*(Aqre connected to $peer_addr";
288 \& }
289 .Ve
290 .PP
291 If the socket is in a connected state, the peer address is returned. If the
292 socket is not in a connected state, \f(CW\*(C`undef\*(C'\fR is returned.
293 .PP
294 Note that this method considers a half-open TCP socket to be "in a connected
295 state". Specifically, it does not distinguish between the
296 \&\fBESTABLISHED\fR and \fBCLOSE-WAIT\fR TCP states; it returns the peer address,
297 rather than \f(CW\*(C`undef\*(C'\fR, in either case. Thus, in general, it cannot
298 be used to reliably learn whether the peer has initiated a graceful shutdown
299 because in most cases (see below) the local TCP state machine remains in
300 \&\fBCLOSE-WAIT\fR until the local application calls "shutdown" in IO::Socket or
301 \&\f(CW\*(C`close\*(C'\fR. Only at that point does this function return \f(CW\*(C`undef\*(C'\fR.
302 .PP
303 The "in most cases" hedge is because local TCP state machine behavior may
304 depend on the peer's socket options. In particular, if the peer socket has
305 \&\f(CW\*(C`SO_LINGER\*(C'\fR enabled with a zero timeout, then the peer's \f(CW\*(C`close\*(C'\fR will
306 generate a \f(CW\*(C`RST\*(C'\fR segment. Upon receipt of that segment, the local TCP
307 transitions immediately to \fBCLOSED\fR, and in that state, this method \fIwill\fR
308 return \f(CW\*(C`undef\*(C'\fR.
309 .SS getsockopt
310 .IX Subsection "getsockopt"
311 .Vb 3
312 \& my $value = $sock\->getsockopt(SOL_SOCKET, SO_REUSEADDR);
313 \& my $buf = $socket\->getsockopt(SOL_SOCKET, SO_RCVBUF);
314 \& say "Receive buffer is $buf bytes";
315 .Ve
316 .PP
317 Get an option associated with the socket. Levels other than \f(CW\*(C`SOL_SOCKET\*(C'\fR
318 may be specified here. As a convenience, this method will unpack a byte buffer
319 of the correct size back into a number.
320 .SS listen
321 .IX Subsection "listen"
322 .Vb 1
323 \& $sock\->listen(5);
324 .Ve
325 .PP
326 Does the same thing that the \f(CWlisten(2)\fR system call does. Returns true if it
327 succeeded, false otherwise. Listens to a socket with a given queue size.
328 .SS peername
329 .IX Subsection "peername"
330 .Vb 1
331 \& my $sockaddr_in = $sock\->peername();
332 .Ve
333 .PP
334 Returns the packed \f(CW\*(C`sockaddr\*(C'\fR address of the other end of the socket
335 connection. It calls \f(CW\*(C`getpeername\*(C'\fR.
336 .SS protocol
337 .IX Subsection "protocol"
338 .Vb 1
339 \& my $proto = $sock\->protocol();
340 .Ve
341 .PP
342 Returns the number for the protocol being used on the socket, if
343 known. If the protocol is unknown, as with an \f(CW\*(C`AF_UNIX\*(C'\fR socket, zero
344 is returned.
345 .SS recv
346 .IX Subsection "recv"
347 .Vb 5
348 \& my $buffer = "";
349 \& my $length = 1024;
350 \& my $flags = 0; # default. optional
351 \& $sock\->recv($buffer, $length);
352 \& $sock\->recv($buffer, $length, $flags);
353 .Ve
354 .PP
355 Similar in functionality to "recv" in perlfunc.
356 .PP
357 Receives a message on a socket. Attempts to receive \f(CW$length\fR characters of
358 data into \f(CW$buffer\fR from the specified socket. \f(CW$buffer\fR will be grown or
359 shrunk to the length actually read. Takes the same flags as the system call of
360 the same name. Returns the address of the sender if socket's protocol supports
361 this; returns an empty string otherwise. If there's an error, returns
362 \&\f(CW\*(C`undef\*(C'\fR. This call is actually implemented in terms of the \f(CWrecvfrom(2)\fR
363 system call.
364 .PP
365 Flags are ORed together values, such as \f(CW\*(C`MSG_BCAST\*(C'\fR, \f(CW\*(C`MSG_OOB\*(C'\fR,
366 \&\f(CW\*(C`MSG_TRUNC\*(C'\fR. The default value for the flags is \f(CW0\fR.
367 .PP
368 The cached value of "peername" in IO::Socket is updated with the result of
369 \&\f(CW\*(C`recv\*(C'\fR.
370 .PP
371 \&\fBNote:\fR In Perl v5.30 and newer, if the socket has been marked as \f(CW\*(C`:utf8\*(C'\fR,
372 \&\f(CW\*(C`recv\*(C'\fR will throw an exception. The \f(CW:encoding(...)\fR layer implicitly
373 introduces the \f(CW\*(C`:utf8\*(C'\fR layer. See "binmode" in perlfunc.
374 .PP
375 \&\fBNote:\fR In Perl versions older than v5.30, depending on the status of the
376 socket, either (8\-bit) bytes or characters are received. By default all
377 sockets operate on bytes, but for example if the socket has been changed
378 using "binmode" in perlfunc to operate with the \f(CW:encoding(UTF\-8)\fR I/O layer
379 (see the "open" in perlfunc pragma), the I/O will operate on UTF8\-encoded
380 Unicode characters, not bytes. Similarly for the \f(CW\*(C`:encoding\*(C'\fR layer: in
381 that case pretty much any characters can be read.
382 .SS send
383 .IX Subsection "send"
384 .Vb 6
385 \& my $message = "Hello, world!";
386 \& my $flags = 0; # defaults to zero
387 \& my $to = \*(Aq0.0.0.0\*(Aq; # optional destination
388 \& my $sent = $sock\->send($message);
389 \& $sent = $sock\->send($message, $flags);
390 \& $sent = $sock\->send($message, $flags, $to);
391 .Ve
392 .PP
393 Similar in functionality to "send" in perlfunc.
394 .PP
395 Sends a message on a socket. Attempts to send the scalar message to the
396 socket. Takes the same flags as the system call of the same name. On
397 unconnected sockets, you must specify a destination to send to, in which case
398 it does a \f(CWsendto(2)\fR syscall. Returns the number of characters sent, or
399 \&\f(CW\*(C`undef\*(C'\fR on error. The \f(CWsendmsg(2)\fR syscall is currently unimplemented.
400 .PP
401 The \f(CW\*(C`flags\*(C'\fR option is optional and defaults to \f(CW0\fR.
402 .PP
403 After a successful send with \f(CW$to\fR, further calls to \f(CW\*(C`send\*(C'\fR on an
404 unconnected socket without \f(CW$to\fR will send to the same address, and \f(CW$to\fR
405 will be used as the result of "peername" in IO::Socket.
406 .PP
407 \&\fBNote:\fR In Perl v5.30 and newer, if the socket has been marked as \f(CW\*(C`:utf8\*(C'\fR,
408 \&\f(CW\*(C`send\*(C'\fR will throw an exception. The \f(CW:encoding(...)\fR layer implicitly
409 introduces the \f(CW\*(C`:utf8\*(C'\fR layer. See "binmode" in perlfunc.
410 .PP
411 \&\fBNote:\fR In Perl versions older than v5.30, depending on the status of the
412 socket, either (8\-bit) bytes or characters are sent. By default all
413 sockets operate on bytes, but for example if the socket has been changed
414 using "binmode" in perlfunc to operate with the \f(CW:encoding(UTF\-8)\fR I/O layer
415 (see the "open" in perlfunc pragma), the I/O will operate on UTF8\-encoded
416 Unicode characters, not bytes. Similarly for the \f(CW\*(C`:encoding\*(C'\fR layer: in
417 that case pretty much any characters can be sent.
418 .SS setsockopt
419 .IX Subsection "setsockopt"
420 .Vb 2
421 \& $sock\->setsockopt(SOL_SOCKET, SO_REUSEADDR, 1);
422 \& $sock\->setsockopt(SOL_SOCKET, SO_RCVBUF, 64*1024);
423 .Ve
424 .PP
425 Set option associated with the socket. Levels other than \f(CW\*(C`SOL_SOCKET\*(C'\fR
426 may be specified here. As a convenience, this method will convert a number
427 into a packed byte buffer.
428 .SS shutdown
429 .IX Subsection "shutdown"
430 .Vb 3
431 \& $sock\->shutdown(SHUT_RD); # we stopped reading data
432 \& $sock\->shutdown(SHUT_WR); # we stopped writing data
433 \& $sock\->shutdown(SHUT_RDWR); # we stopped using this socket
434 .Ve
435 .PP
436 Shuts down a socket connection in the manner indicated by the value passed in,
437 which has the same interpretation as in the syscall of the same name.
438 .PP
439 This is useful with sockets when you want to tell the other side you're done
440 writing but not done reading, or vice versa. It's also a more insistent form
441 of \f(CW\*(C`close\*(C'\fR because it also disables the file descriptor in any
442 forked copies in other processes.
443 .PP
444 Returns \f(CW1\fR for success; on error, returns \f(CW\*(C`undef\*(C'\fR if the socket is
445 not a valid filehandle, or returns \f(CW0\fR and sets \f(CW$!\fR for any other failure.
446 .SS sockdomain
447 .IX Subsection "sockdomain"
448 .Vb 1
449 \& my $domain = $sock\->sockdomain();
450 .Ve
451 .PP
452 Returns the number for the socket domain type. For example, for
453 an \f(CW\*(C`AF_INET\*(C'\fR socket the value of \f(CW&AF_INET\fR will be returned.
454 .SS socket
455 .IX Subsection "socket"
456 .Vb 4
457 \& my $sock = IO::Socket\->new(); # no values given
458 \& # now let\*(Aqs actually get a socket with the socket method
459 \& # domain, type, and protocol are required
460 \& $sock = $sock\->socket(AF_INET, SOCK_STREAM, \*(Aqtcp\*(Aq);
461 .Ve
462 .PP
463 Opens a socket of the specified kind and returns it. Domain, type, and
464 protocol are specified the same as for the syscall of the same name.
465 .SS socketpair
466 .IX Subsection "socketpair"
467 .Vb 3
468 \& my ($r, $w) = $sock\->socketpair(AF_UNIX, SOCK_STREAM, PF_UNSPEC);
469 \& ($r, $w) = IO::Socket::UNIX
470 \& \->socketpair(AF_UNIX, SOCK_STREAM, PF_UNSPEC);
471 .Ve
472 .PP
473 Will return a list of two sockets created (read and write), or an empty list
474 on failure.
475 .PP
476 Differs slightly from \f(CW\*(C`socketpair\*(C'\fR in perlfunc in that the argument list
477 is a bit simpler.
478 .SS sockname
479 .IX Subsection "sockname"
480 .Vb 1
481 \& my $packed_addr = $sock\->sockname();
482 .Ve
483 .PP
484 Returns the packed \f(CW\*(C`sockaddr\*(C'\fR address of this end of the connection. It's the
485 same as \f(CWgetsockname(2)\fR.
486 .SS sockopt
487 .IX Subsection "sockopt"
488 .Vb 2
489 \& my $value = $sock\->sockopt(SO_REUSEADDR);
490 \& $sock\->sockopt(SO_REUSEADDR, 1);
491 .Ve
492 .PP
493 Unified method to both set and get options in the \f(CW\*(C`SOL_SOCKET\*(C'\fR level. If
494 called with one argument then "getsockopt" in IO::Socket is called, otherwise
495 "setsockopt" in IO::Socket is called.
496 .SS socktype
497 .IX Subsection "socktype"
498 .Vb 1
499 \& my $type = $sock\->socktype();
500 .Ve
501 .PP
502 Returns the number for the socket type. For example, for
503 a \f(CW\*(C`SOCK_STREAM\*(C'\fR socket the value of \f(CW&SOCK_STREAM\fR will be returned.
504 .SS timeout
505 .IX Subsection "timeout"
506 .Vb 2
507 \& my $seconds = $sock\->timeout();
508 \& my $old_val = $sock\->timeout(5); # set new and return old value
509 .Ve
510 .PP
511 Set or get the timeout value (in seconds) associated with this socket.
512 If called without any arguments then the current setting is returned. If
513 called with an argument the current setting is changed and the previous
514 value returned.
515 .PP
516 This method is available to all \f(CW\*(C`IO::Socket\*(C'\fR implementations but may or may
517 not be used by the individual domain subclasses.
518 .SH EXAMPLES
519 .IX Header "EXAMPLES"
520 Let's create a TCP server on \f(CW\*(C`localhost:3333\*(C'\fR.
521 .PP
522 .Vb 3
523 \& use strict;
524 \& use warnings;
525 \& use feature \*(Aqsay\*(Aq;
526 \&
527 \& use IO::Socket qw(AF_INET AF_UNIX SOCK_STREAM SHUT_WR);
528 \&
529 \& my $server = IO::Socket\->new(
530 \& Domain => AF_INET,
531 \& Type => SOCK_STREAM,
532 \& Proto => \*(Aqtcp\*(Aq,
533 \& LocalHost => \*(Aq0.0.0.0\*(Aq,
534 \& LocalPort => 3333,
535 \& ReusePort => 1,
536 \& Listen => 5,
537 \& ) || die "Can\*(Aqt open socket: $IO::Socket::errstr";
538 \& say "Waiting on 3333";
539 \&
540 \& while (1) {
541 \& # waiting for a new client connection
542 \& my $client = $server\->accept();
543 \&
544 \& # get information about a newly connected client
545 \& my $client_address = $client\->peerhost();
546 \& my $client_port = $client\->peerport();
547 \& say "Connection from $client_address:$client_port";
548 \&
549 \& # read up to 1024 characters from the connected client
550 \& my $data = "";
551 \& $client\->recv($data, 1024);
552 \& say "received data: $data";
553 \&
554 \& # write response data to the connected client
555 \& $data = "ok";
556 \& $client\->send($data);
557 \&
558 \& # notify client that response has been sent
559 \& $client\->shutdown(SHUT_WR);
560 \& }
561 \&
562 \& $server\->close();
563 .Ve
564 .PP
565 A client for such a server could be
566 .PP
567 .Vb 3
568 \& use strict;
569 \& use warnings;
570 \& use feature \*(Aqsay\*(Aq;
571 \&
572 \& use IO::Socket qw(AF_INET AF_UNIX SOCK_STREAM SHUT_WR);
573 \&
574 \& my $client = IO::Socket\->new(
575 \& Domain => AF_INET,
576 \& Type => SOCK_STREAM,
577 \& proto => \*(Aqtcp\*(Aq,
578 \& PeerPort => 3333,
579 \& PeerHost => \*(Aq0.0.0.0\*(Aq,
580 \& ) || die "Can\*(Aqt open socket: $IO::Socket::errstr";
581 \&
582 \& say "Sending Hello World!";
583 \& my $size = $client\->send("Hello World!");
584 \& say "Sent data of length: $size";
585 \&
586 \& $client\->shutdown(SHUT_WR);
587 \&
588 \& my $buffer;
589 \& $client\->recv($buffer, 1024);
590 \& say "Got back $buffer";
591 \&
592 \& $client\->close();
593 .Ve
594 .SH LIMITATIONS
595 .IX Header "LIMITATIONS"
596 On some systems, for an IO::Socket object created with \f(CW\*(C`new_from_fd\*(C'\fR,
597 or created with "accept" in IO::Socket from such an object, the
598 "protocol" in IO::Socket, "sockdomain" in IO::Socket and
599 "socktype" in IO::Socket methods may return \f(CW\*(C`undef\*(C'\fR.
600 .SH "SEE ALSO"
601 .IX Header "SEE ALSO"
602 Socket, IO::Handle, IO::Socket::INET, IO::Socket::UNIX,
603 IO::Socket::IP
604 .SH AUTHOR
605 .IX Header "AUTHOR"
606 Graham Barr. \fBatmark()\fR by Lincoln Stein. Currently maintained by the Perl 5
607 Porters. Please report all bugs at <https://github.com/Perl/perl5/issues>.
608 .SH COPYRIGHT
609 .IX Header "COPYRIGHT"
610 Copyright (c) 1997\-8 Graham Barr <[email protected]>. All rights reserved.
611 This program is free software; you can redistribute it and/or
612 modify it under the same terms as Perl itself.
613 .PP
614 The \fBatmark()\fR implementation: Copyright 2001, Lincoln Stein <[email protected]>.
615 This module is distributed under the same terms as Perl itself.
616 Feel free to use, modify and redistribute it as long as you retain
617 the correct attribution.