1Net::EmptyPort(3)     User Contributed Perl Documentation    Net::EmptyPort(3)
2
3
4

NAME

6       Net::EmptyPort - find a free TCP/UDP port
7

SYNOPSIS

9           use Net::EmptyPort qw(empty_port check_port);
10
11           # get a socket listening on a random free port
12           my $socket = listen_socket();
13
14           # get a random free port
15           my $port = empty_port();
16
17           # check if a port is already used
18           if (check_port(5000)) {
19               say "Port 5000 already in use";
20           }
21

DESCRIPTION

23       Net::EmptyPort helps finding an empty TCP/UDP port.
24

METHODS

26       "listen_socket()"
27       "listen_socket(\%args)"
28               my $socket = listen_socket();
29
30           Returns a socket listening on a free port.
31
32           The function recognizes the following keys in the hashref argument.
33
34           "host"
35               The address on which to listen.  Default is 127.0.0.1.
36
37           "proto"
38               Name of the protocol.  Default is "tcp".  You can get an UDP
39               socket by specifying "udp".
40
41       "empty_port()"
42       "empty_port(\%args)"
43       "empty_port($port)"
44       "empty_port($port, $proto)"
45               my $port = empty_port();
46
47           Returns a port number that is NOT in use.
48
49           The function recognizes the following keys when given a hashref as
50           the argument.
51
52           "host"
53               specifies the address on which the search should be performed.
54               Default is 127.0.0.1.
55
56           "port"
57               Lower bound of the search for an empty port.  If omitted, the
58               function searches for an empty port within 49152..65535.
59
60               See <http://www.iana.org/assignments/port-numbers>
61
62           "proto"
63               Name of the protocol.  Default is "tcp". You can find an empty
64               UDP port by specifying "udp".
65
66           To maintain backwards compatibility, the function accepts scalar
67           arguments as well.  For example, you can also find an empty UDP
68           port by specifying the protocol as the second parameter:
69
70               my $port = empty_port(1024, 'udp');
71               # use 49152..65535 range
72               my $port = empty_port(undef, 'udp');
73
74       "check_port(\%args)"
75       "check_port($port)"
76       "check_port($port, $proto)"
77               my $true_or_false = check_port(5000);
78
79           Checks if the given port is already in use. Returns true if it is
80           in use (i.e. if the port is NOT free). Returns false if the port is
81           free.
82
83           The function recognizes the following keys when given a hashref as
84           the argument.
85
86           When UDP is specified as the protocol, the `check_port` function
87           sends a probe UDP packet to the designated port to see if an ICMP
88           error message is returned, which indicates that the port is
89           unassigned.  The port is assumed to be assigned, unless such
90           response is observed within 0.1 seconds.
91
92           "host"
93               specifies the address on which the search should be performed.
94               Default is 127.0.0.1.
95
96           "port"
97               specifies the port to check.  This argument is mandatory.
98
99           "proto"
100               name of the protocol.  Default is "tcp".
101
102           To maintain backwards compatibility, the function accepts scalar
103           arguments as well in the form described above.
104
105       "wait_port(\%args)"
106       "wait_port($port)"
107       "wait_port($port, $max_wait)"
108       "wait_port($port, $max_wait, $proto)"
109           Waits until a particular port becomes ready to connect to.  Returns
110           true if the port becomes ready, or false if otherwise.
111
112           The function recognizes the following keys when given a hashref as
113           the argument.
114
115           "host"
116               specifies the address on which the search should be performed.
117               Default is 127.0.0.1.
118
119           "port"
120               specifies the port to check.  This argument is mandatory.
121
122           "max_wait"
123               maximum seconds to wait for (default is 10 seconds).  Pass a
124               negative value to wait infinitely.
125
126           "proto"
127               name of the protocol.  Default is "tcp".
128
129           To maintain backwards compatibility, the function accepts scalar
130           arguments as well in the form described above.
131
132           Incompatible changes: Before 2.0, "wait_port($port:Int[,
133           $sleep:Number, $retry:Int, $proto:String])" is a signature.
134
135       "can_bind($host)"
136       "can_bind($host, $port)"
137       "can_bind($host, $port, $proto)"
138           Checks if the application is capable of binding to given port.
139

AUTHOR

141       Tokuhiro Matsuno <tokuhirom@gmail.com>
142

THANKS TO

144       kazuhooku
145
146       dragon3
147
148       charsbar
149
150       Tatsuhiko Miyagawa
151
152       lestrrat
153

SEE ALSO

LICENSE

156       This library is free software; you can redistribute it and/or modify it
157       under the same terms as Perl itself.
158
159
160
161perl v5.32.1                      2021-01-27                 Net::EmptyPort(3)