Debian Codegraph @

upstream/mageia-cauldron/man3pm/IO::Socket.3pm

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