Debian Codegraph @

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