.\" Automatically generated by Pod::Man 4.11 (Pod::Simple 3.35)
.\"
.\" Standard preamble:
.\" ========================================================================
.de Sp \" Vertical space (when we can't use .PP)
.if t .sp .5v
.if n .sp
..
.de Vb \" Begin verbatim text
.ft CW
.nf
.ne \\$1
..
.de Ve \" End verbatim text
.ft R
.fi
..
.\" Set up some character translations and predefined strings.  \*(-- will
.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
.\" double quote, and \*(R" will give a right double quote.  \*(C+ will
.\" give a nicer C++.  Capital omega is used to do unbreakable dashes and
.\" therefore won't be available.  \*(C` and \*(C' expand to `' in nroff,
.\" nothing in troff, for use with C<>.
.tr \(*W-
.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
.ie n \{\
.    ds -- \(*W-
.    ds PI pi
.    if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
.    if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\"  diablo 12 pitch
.    ds L" ""
.    ds R" ""
.    ds C` ""
.    ds C' ""
'br\}
.el\{\
.    ds -- \|\(em\|
.    ds PI \(*p
.    ds L" ``
.    ds R" ''
.    ds C`
.    ds C'
'br\}
.\"
.\" Escape single quotes in literal strings from groff's Unicode transform.
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.\"
.\" If the F register is >0, we'll generate index entries on stderr for
.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
.\" entries marked with X<> in POD.  Of course, you'll have to process the
.\" output yourself in some meaningful fashion.
.\"
.\" Avoid warning from groff about undefined register 'F'.
.de IX
..
.nr rF 0
.if \n(.g .if rF .nr rF 1
.if (\n(rF:(\n(.g==0)) \{\
.    if \nF \{\
.        de IX
.        tm Index:\\$1\t\\n%\t"\\$2"
..
.        if !\nF==2 \{\
.            nr % 0
.            nr F 2
.        \}
.    \}
.\}
.rr rF
.\" ========================================================================
.\"
.IX Title "Net::EmptyPort 3pm"
.TH Net::EmptyPort 3pm "2020-09-08" "perl v5.30.3" "User Contributed Perl Documentation"
.\" For nroff, turn off justification.  Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.if n .ad l
.nh
.SH "NAME"
Net::EmptyPort \- find a free TCP/UDP port
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
.Vb 1
\&    use Net::EmptyPort qw(empty_port check_port);
\&
\&    # get a socket listening on a random free port
\&    my $socket = listen_socket();
\&
\&    # get a random free port
\&    my $port = empty_port();
\&
\&    # check if a port is already used
\&    if (check_port(5000)) {
\&        say "Port 5000 already in use";
\&    }
.Ve
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
Net::EmptyPort helps finding an empty \s-1TCP/UDP\s0 port.
.SH "METHODS"
.IX Header "METHODS"
.ie n .IP """listen_socket()""" 4
.el .IP "\f(CWlisten_socket()\fR" 4
.IX Item "listen_socket()"
.PD 0
.ie n .IP """listen_socket(\e%args)""" 4
.el .IP "\f(CWlisten_socket(\e%args)\fR" 4
.IX Item "listen_socket(%args)"
.PD
.Vb 1
\&    my $socket = listen_socket();
.Ve
.Sp
Returns a socket listening on a free port.
.Sp
The function recognizes the following keys in the hashref argument.
.RS 4
.ie n .IP """host""" 4
.el .IP "\f(CWhost\fR" 4
.IX Item "host"
The address on which to listen.  Default is \f(CW127.0.0.1\fR.
.ie n .IP """proto""" 4
.el .IP "\f(CWproto\fR" 4
.IX Item "proto"
Name of the protocol.  Default is \f(CW\*(C`tcp\*(C'\fR.
You can get an \s-1UDP\s0 socket by specifying \f(CW\*(C`udp\*(C'\fR.
.RE
.RS 4
.RE
.ie n .IP """empty_port()""" 4
.el .IP "\f(CWempty_port()\fR" 4
.IX Item "empty_port()"
.PD 0
.ie n .IP """empty_port(\e%args)""" 4
.el .IP "\f(CWempty_port(\e%args)\fR" 4
.IX Item "empty_port(%args)"
.ie n .IP """empty_port($port)""" 4
.el .IP "\f(CWempty_port($port)\fR" 4
.IX Item "empty_port($port)"
.ie n .IP """empty_port($port, $proto)""" 4
.el .IP "\f(CWempty_port($port, $proto)\fR" 4
.IX Item "empty_port($port, $proto)"
.PD
.Vb 1
\&    my $port = empty_port();
.Ve
.Sp
Returns a port number that is \s-1NOT\s0 in use.
.Sp
The function recognizes the following keys when given a hashref as the argument.
.RS 4
.ie n .IP """host""" 4
.el .IP "\f(CWhost\fR" 4
.IX Item "host"
specifies the address on which the search should be performed.  Default is \f(CW127.0.0.1\fR.
.ie n .IP """port""" 4
.el .IP "\f(CWport\fR" 4
.IX Item "port"
Lower bound of the search for an empty port.  If omitted, the function searches for an empty port within 49152..65535.
.Sp
See <http://www.iana.org/assignments/port\-numbers>
.ie n .IP """proto""" 4
.el .IP "\f(CWproto\fR" 4
.IX Item "proto"
Name of the protocol.  Default is \f(CW\*(C`tcp\*(C'\fR. You can find an empty \s-1UDP\s0 port by specifying \f(CW\*(C`udp\*(C'\fR.
.RE
.RS 4
.Sp
To maintain backwards compatibility, the function accepts scalar arguments as well.  For example, you can also find an empty \s-1UDP\s0 port by specifying the protocol as
the second parameter:
.Sp
.Vb 3
\&    my $port = empty_port(1024, \*(Aqudp\*(Aq);
\&    # use 49152..65535 range
\&    my $port = empty_port(undef, \*(Aqudp\*(Aq);
.Ve
.RE
.ie n .IP """check_port(\e%args)""" 4
.el .IP "\f(CWcheck_port(\e%args)\fR" 4
.IX Item "check_port(%args)"
.PD 0
.ie n .IP """check_port($port)""" 4
.el .IP "\f(CWcheck_port($port)\fR" 4
.IX Item "check_port($port)"
.ie n .IP """check_port($port, $proto)""" 4
.el .IP "\f(CWcheck_port($port, $proto)\fR" 4
.IX Item "check_port($port, $proto)"
.PD
.Vb 1
\&    my $true_or_false = check_port(5000);
.Ve
.Sp
Checks if the given port is already in use. Returns true if it is in use (i.e. if the port is \s-1NOT\s0 free). Returns false if the port is free.
.Sp
The function recognizes the following keys when given a hashref as the argument.
.Sp
When \s-1UDP\s0 is specified as the protocol, the `check_port` function sends a probe \s-1UDP\s0 packet to the designated port to see if an \s-1ICMP\s0 error message is returned, which indicates that the port is unassigned.  The port is assumed to be assigned, unless such response is observed within 0.1 seconds.
.RS 4
.ie n .IP """host""" 4
.el .IP "\f(CWhost\fR" 4
.IX Item "host"
specifies the address on which the search should be performed.  Default is \f(CW127.0.0.1\fR.
.ie n .IP """port""" 4
.el .IP "\f(CWport\fR" 4
.IX Item "port"
specifies the port to check.  This argument is mandatory.
.ie n .IP """proto""" 4
.el .IP "\f(CWproto\fR" 4
.IX Item "proto"
name of the protocol.  Default is \f(CW\*(C`tcp\*(C'\fR.
.RE
.RS 4
.Sp
To maintain backwards compatibility, the function accepts scalar arguments as well in the form described above.
.RE
.ie n .IP """wait_port(\e%args)""" 4
.el .IP "\f(CWwait_port(\e%args)\fR" 4
.IX Item "wait_port(%args)"
.PD 0
.ie n .IP """wait_port($port)""" 4
.el .IP "\f(CWwait_port($port)\fR" 4
.IX Item "wait_port($port)"
.ie n .IP """wait_port($port, $max_wait)""" 4
.el .IP "\f(CWwait_port($port, $max_wait)\fR" 4
.IX Item "wait_port($port, $max_wait)"
.ie n .IP """wait_port($port, $max_wait, $proto)""" 4
.el .IP "\f(CWwait_port($port, $max_wait, $proto)\fR" 4
.IX Item "wait_port($port, $max_wait, $proto)"
.PD
Waits until a particular port becomes ready to connect to.  Returns true if the port becomes ready, or false if otherwise.
.Sp
The function recognizes the following keys when given a hashref as the argument.
.RS 4
.ie n .IP """host""" 4
.el .IP "\f(CWhost\fR" 4
.IX Item "host"
specifies the address on which the search should be performed.  Default is \f(CW127.0.0.1\fR.
.ie n .IP """port""" 4
.el .IP "\f(CWport\fR" 4
.IX Item "port"
specifies the port to check.  This argument is mandatory.
.ie n .IP """max_wait""" 4
.el .IP "\f(CWmax_wait\fR" 4
.IX Item "max_wait"
maximum seconds to wait for (default is 10 seconds).  Pass a negative value to wait infinitely.
.ie n .IP """proto""" 4
.el .IP "\f(CWproto\fR" 4
.IX Item "proto"
name of the protocol.  Default is \f(CW\*(C`tcp\*(C'\fR.
.RE
.RS 4
.Sp
To maintain backwards compatibility, the function accepts scalar arguments as well in the form described above.
.Sp
\&\fBIncompatible changes\fR: Before 2.0, \f(CW\*(C`wait_port($port:Int[, $sleep:Number, $retry:Int, $proto:String])\*(C'\fR is a signature.
.RE
.ie n .IP """can_bind($host)""" 4
.el .IP "\f(CWcan_bind($host)\fR" 4
.IX Item "can_bind($host)"
.PD 0
.ie n .IP """can_bind($host, $port)""" 4
.el .IP "\f(CWcan_bind($host, $port)\fR" 4
.IX Item "can_bind($host, $port)"
.ie n .IP """can_bind($host, $port, $proto)""" 4
.el .IP "\f(CWcan_bind($host, $port, $proto)\fR" 4
.IX Item "can_bind($host, $port, $proto)"
.PD
Checks if the application is capable of binding to given port.
.SH "AUTHOR"
.IX Header "AUTHOR"
Tokuhiro Matsuno <tokuhirom@gmail.com>
.SH "THANKS TO"
.IX Header "THANKS TO"
kazuhooku
.PP
dragon3
.PP
charsbar
.PP
Tatsuhiko Miyagawa
.PP
lestrrat
.SH "SEE ALSO"
.IX Header "SEE ALSO"
.SH "LICENSE"
.IX Header "LICENSE"
This library is free software; you can redistribute it and/or modify
it under the same terms as Perl itself.