NAME

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

SYNOPSIS

           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";
           }

DESCRIPTION

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

METHODS

       "listen_socket()"
       "listen_socket(\%args)"
               my $socket = listen_socket();

           Returns a socket listening on a free port.

           The function recognizes the following keys in the hashref argument.

           "host"
               The address on which to listen.  Default is 127.0.0.1.

           "proto"
               Name of the protocol.  Default is "tcp".  You can get an UDP socket by specifying "udp".

       "empty_port()"
       "empty_port(\%args)"
       "empty_port($port)"
       "empty_port($port, $proto)"
               my $port = empty_port();

           Returns a port number that is NOT in use.

           The function recognizes the following keys when given a hashref as the argument.

           "host"
               specifies the address on which the search should be performed.  Default is 127.0.0.1.

           "port"
               Lower bound of the search for an empty port.  If omitted, the function searches for an empty port
               within 49152..65535.

               See <http://www.iana.org/assignments/port-numbers>

           "proto"
               Name of the protocol.  Default is "tcp". You can find an empty UDP port by specifying "udp".

           To maintain backwards compatibility, the function accepts scalar arguments as well.  For example, you
           can also find an empty UDP port by specifying the protocol as the second parameter:

               my $port = empty_port(1024, 'udp');
               # use 49152..65535 range
               my $port = empty_port(undef, 'udp');

       "check_port(\%args)"
       "check_port($port)"
       "check_port($port, $proto)"
               my $true_or_false = check_port(5000);

           Checks  if  the  given  port is already in use. Returns true if it is in use (i.e. if the port is NOT
           free). Returns false if the port is free.

           The function recognizes the following keys when given a hashref as the argument.

           When UDP is specified as the protocol, the `check_port` function sends a  probe  UDP  packet  to  the
           designated  port  to  see  if  an  ICMP  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.

           "host"
               specifies the address on which the search should be performed.  Default is 127.0.0.1.

           "port"
               specifies the port to check.  This argument is mandatory.

           "proto"
               name of the protocol.  Default is "tcp".

           To maintain backwards compatibility, the function accepts  scalar  arguments  as  well  in  the  form
           described above.

       "wait_port(\%args)"
       "wait_port($port)"
       "wait_port($port, $max_wait)"
       "wait_port($port, $max_wait, $proto)"
           Waits  until  a particular port becomes ready to connect to.  Returns true if the port becomes ready,
           or false if otherwise.

           The function recognizes the following keys when given a hashref as the argument.

           "host"
               specifies the address on which the search should be performed.  Default is 127.0.0.1.

           "port"
               specifies the port to check.  This argument is mandatory.

           "max_wait"
               maximum seconds to wait for (default is 10 seconds).  Pass a negative value to wait infinitely.

           "proto"
               name of the protocol.  Default is "tcp".

           To maintain backwards compatibility, the function accepts  scalar  arguments  as  well  in  the  form
           described above.

           Incompatible  changes: Before 2.0, "wait_port($port:Int[, $sleep:Number, $retry:Int, $proto:String])"
           is a signature.

       "can_bind($host)"
       "can_bind($host, $port)"
       "can_bind($host, $port, $proto)"
           Checks if the application is capable of binding to given port.

AUTHOR

       Tokuhiro Matsuno <tokuhirom@gmail.com>

THANKS TO

       kazuhooku

       dragon3

       charsbar

       Tatsuhiko Miyagawa

       lestrrat

SEE ALSO

LICENSE

       This library is free software; you can redistribute it and/or modify it under  the  same  terms  as  Perl
       itself.

perl v5.30.3                                       2020-09-08                                Net::EmptyPort(3pm)