| 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. |