Debian Codegraph @

upstream/opensuse-tumbleweed/man3/IO::Socket::INET.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::INET 3pm"
61 .TH IO::Socket::INET 3pm 2026-03-09 "perl v5.42.1" "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::INET \- Object interface for AF_INET domain sockets
68 .SH SYNOPSIS
69 .IX Header "SYNOPSIS"
70 .Vb 1
71 \& use IO::Socket::INET;
72 .Ve
73 .SH DESCRIPTION
74 .IX Header "DESCRIPTION"
75 \&\f(CW\*(C`IO::Socket::INET\*(C'\fR provides an object interface to creating and using sockets
76 in the AF_INET domain. It is built upon the IO::Socket interface and
77 inherits all the methods defined by IO::Socket.
78 .SH CONSTRUCTOR
79 .IX Header "CONSTRUCTOR"
80 .IP "new ( [ARGS] )" 4
81 .IX Item "new ( [ARGS] )"
82 Creates an \f(CW\*(C`IO::Socket::INET\*(C'\fR object, which is a reference to a
83 newly created symbol (see the Symbol package). \f(CW\*(C`new\*(C'\fR
84 optionally takes arguments, these arguments are in key\-value pairs.
85 .Sp
86 In addition to the key\-value pairs accepted by IO::Socket,
87 \&\f(CW\*(C`IO::Socket::INET\*(C'\fR provides.
88 .Sp
89 .Vb 10
90 \& PeerAddr Remote host address <hostname>[:<port>]
91 \& PeerHost Synonym for PeerAddr
92 \& PeerPort Remote port or service <service>[(<no>)] | <no>
93 \& LocalAddr Local host bind address hostname[:port]
94 \& LocalHost Synonym for LocalAddr
95 \& LocalPort Local host bind port <service>[(<no>)] | <no>
96 \& Proto Protocol name (or number) "tcp" | "udp" | ...
97 \& Type Socket type SOCK_STREAM | SOCK_DGRAM | ...
98 \& Listen Queue size for listen
99 \& ReuseAddr Set SO_REUSEADDR before binding
100 \& Reuse Set SO_REUSEADDR before binding (deprecated,
101 \& prefer ReuseAddr)
102 \& ReusePort Set SO_REUSEPORT before binding
103 \& Broadcast Set SO_BROADCAST before binding
104 \& Timeout Timeout value for various operations
105 \& MultiHomed Try all addresses for multi\-homed hosts
106 \& Blocking Determine if connection will be blocking mode
107 .Ve
108 .Sp
109 If \f(CW\*(C`Listen\*(C'\fR is defined then a listen socket is created, else if the
110 socket type, which is derived from the protocol, is SOCK_STREAM then
111 \&\fBconnect()\fR is called. If the \f(CW\*(C`Listen\*(C'\fR argument is given, but false,
112 the queue size will be set to 5.
113 .Sp
114 Although it is not illegal, the use of \f(CW\*(C`MultiHomed\*(C'\fR on a socket
115 which is in non\-blocking mode is of little use. This is because the
116 first connect will never fail with a timeout as the connect call
117 will not block.
118 .Sp
119 The \f(CW\*(C`PeerAddr\*(C'\fR can be a hostname or the IP\-address on the
120 "xx.xx.xx.xx" form. The \f(CW\*(C`PeerPort\*(C'\fR can be a number or a symbolic
121 service name. The service name might be followed by a number in
122 parenthesis which is used if the service is not known by the system.
123 The \f(CW\*(C`PeerPort\*(C'\fR specification can also be embedded in the \f(CW\*(C`PeerAddr\*(C'\fR
124 by preceding it with a ":".
125 .Sp
126 If \f(CW\*(C`Proto\*(C'\fR is not given and you specify a symbolic \f(CW\*(C`PeerPort\*(C'\fR port,
127 then the constructor will try to derive \f(CW\*(C`Proto\*(C'\fR from the service
128 name. As a last resort \f(CW\*(C`Proto\*(C'\fR "tcp" is assumed. The \f(CW\*(C`Type\*(C'\fR
129 parameter will be deduced from \f(CW\*(C`Proto\*(C'\fR if not specified.
130 .Sp
131 If the constructor is only passed a single argument, it is assumed to
132 be a \f(CW\*(C`PeerAddr\*(C'\fR specification.
133 .Sp
134 If \f(CW\*(C`Blocking\*(C'\fR is set to 0, the connection will be in nonblocking mode.
135 If not specified it defaults to 1 (blocking mode).
136 .Sp
137 Examples:
138 .Sp
139 .Vb 3
140 \& $sock = IO::Socket::INET\->new(PeerAddr => \*(Aqwww.perl.org\*(Aq,
141 \& PeerPort => \*(Aqhttp(80)\*(Aq,
142 \& Proto => \*(Aqtcp\*(Aq);
143 \&
144 \& $sock = IO::Socket::INET\->new(PeerAddr => \*(Aqlocalhost:smtp(25)\*(Aq);
145 \&
146 \& $sock = IO::Socket::INET\->new(Listen => 5,
147 \& LocalAddr => \*(Aqlocalhost\*(Aq,
148 \& LocalPort => 9000,
149 \& Proto => \*(Aqtcp\*(Aq);
150 \&
151 \& $sock = IO::Socket::INET\->new(\*(Aq127.0.0.1:25\*(Aq);
152 \&
153 \& $sock = IO::Socket::INET\->new(
154 \& PeerPort => 9999,
155 \& PeerAddr => inet_ntoa(INADDR_BROADCAST),
156 \& Proto => \*(Aqudp\*(Aq,
157 \& LocalAddr => \*(Aqlocalhost\*(Aq,
158 \& Broadcast => 1 )
159 \& or die "Can\*(Aqt bind : $IO::Socket::errstr\en";
160 .Ve
161 .Sp
162 If the constructor fails it will return \f(CW\*(C`undef\*(C'\fR and set the
163 \&\f(CW$IO::Socket::errstr\fR package variable to contain an error message.
164 .Sp
165 .Vb 2
166 \& $sock = IO::Socket::INET\->new(...)
167 \& or die "Cannot create socket \- $IO::Socket::errstr\en";
168 .Ve
169 .Sp
170 For legacy reasons the error message is also set into the global \f(CW$@\fR
171 variable, and you may still find older code which looks here instead.
172 .Sp
173 .Vb 2
174 \& $sock = IO::Socket::INET\->new(...)
175 \& or die "Cannot create socket \- $@\en";
176 .Ve
177 .SS METHODS
178 .IX Subsection "METHODS"
179 .IP "sockaddr ()" 4
180 .IX Item "sockaddr ()"
181 Return the address part of the sockaddr structure for the socket
182 .IP "sockport ()" 4
183 .IX Item "sockport ()"
184 Return the port number that the socket is using on the local host
185 .IP "sockhost ()" 4
186 .IX Item "sockhost ()"
187 Return the address part of the sockaddr structure for the socket in a
188 text form xx.xx.xx.xx
189 .IP "peeraddr ()" 4
190 .IX Item "peeraddr ()"
191 Return the address part of the sockaddr structure for the socket on
192 the peer host
193 .IP "peerport ()" 4
194 .IX Item "peerport ()"
195 Return the port number for the socket on the peer host.
196 .IP "peerhost ()" 4
197 .IX Item "peerhost ()"
198 Return the address part of the sockaddr structure for the socket on the
199 peer host in a text form xx.xx.xx.xx
200 .SH "SEE ALSO"
201 .IX Header "SEE ALSO"
202 Socket, IO::Socket
203 .SH AUTHOR
204 .IX Header "AUTHOR"
205 Graham Barr. Currently maintained by the Perl Porters. Please report all
206 bugs at <https://github.com/Perl/perl5/issues>.
207 .SH COPYRIGHT
208 .IX Header "COPYRIGHT"
209 Copyright (c) 1996\-8 Graham Barr <[email protected]>. All rights reserved.
210 This program is free software; you can redistribute it and/or
211 modify it under the same terms as Perl itself.