go_getport

README

getport

A simple Go module that provides methods for find an open port on the local system. A comprehensive set of methods for getting open TCP or UDP ports on either the IPv4 or IPv6 network stacks are provided.

Install

$ go get github.com/jsumners/go-getport

Example

The following example shows a simple TCP server that will write hello world and close the connection when a connection is made, e.g. via netcat (nc 127.0.0.1 <discovered-port>).

package main

import (
	getport "github.com/jsumners/go-getport"
	"net"
)

func main() {
	// Get an open TCP port on the localhost address.
	// `getport.GetTcpPort()` would instead listen on all addresses with
	// a common free port.
	portResult, getPortError := getport.GetTcpPortForAddress("127.0.0.1")
	if getPortError != nil {
		panic(getPortError)
	}

	listenAddress := getport.PortResultToAddress(portResult)
	listener, listenError := net.Listen("tcp", listenAddress)
	if listenError != nil {
		panic(listenError)
	}

	println("listening on: ", listenAddress)
	defer listener.Close()

	connection, connError := listener.Accept()
	if connError != nil {
		panic(connError)
	}

	connection.Write([]byte("hello world"))
	connection.Close()
}

Documentation

Index

• func PortResultToAddress(portResult PortResult) string
• type PortResult
  • func GetPort(protocol Protocol, address string) (PortResult, error)
  • func GetTcp4Port() (PortResult, error)
  • func GetTcp4PortForAddress(address string) (PortResult, error)
  • func GetTcp6Port() (PortResult, error)
  • func GetTcp6PortForAddress(address string) (PortResult, error)
  • func GetTcpPort() (PortResult, error)
  • func GetTcpPortForAddress(address string) (PortResult, error)
  • func GetUdp4Port() (PortResult, error)
  • func GetUdp4PortForAddress(address string) (PortResult, error)
  • func GetUdp6Port() (PortResult, error)
  • func GetUdp6PortForAddress(address string) (PortResult, error)
  • func GetUdpPort() (PortResult, error)
  • func GetUdpPortForAddress(address string) (PortResult, error)
• type Protocol

Functions

func PortResultToAddress

func PortResultToAddress(portResult PortResult) string

PortResultToAddress converts a PortResult into a traditional host:port string usable by net.Listen or net.ListenPacket.

Types

type PortResult

type PortResult struct {
	// IP is either an IPv4 or IPv6 string as returned by [net.SplitHostPort].
	IP string

	// Port is the determined available port number.
	Port int
}

PortResult represents the result of GetPort. It indicates the IP address and port number combination that resulted in finding an open port.

func GetPort

func GetPort(protocol Protocol, address string) (PortResult, error)

GetPort finds an open port for a given Protocol and address and returns that port number. If the Protocol is not recognized, or some problem is encountered while verifying the port, then the returned [PortResult.Port] number will be `-1` along with an error. The address parameter should be a simple IP address string, e.g. `127.0.0.1` or `::1`. The [PortResult.IP] will be set to the IP address that was actually used to find the open port. If address is the empty string (`""`), then the returned IP address will be the one determined by the OS when finding the port.

Note: it is not guaranteed the port will remain open long enough to actually be used. Errors should still be checked when attempting to use the found port.

func GetTcp4Port

func GetTcp4Port() (PortResult, error)

GetTcp4Port gets a port for some random available address using TCP4. See GetPort for more detail

func GetTcp4PortForAddress

func GetTcp4PortForAddress(address string) (PortResult, error)

GetTcp4PortForAddress gets a TCP4 port for the given address. See GetPort for more detail.

func GetTcp6Port

func GetTcp6Port() (PortResult, error)

GetTcp6Port gets a port for some random available address using TCP6. See GetPort for more detail

func GetTcp6PortForAddress

func GetTcp6PortForAddress(address string) (PortResult, error)

GetTcp6PortForAddress gets a TCP6 port for the given address. See GetPort for more detail.

func GetTcpPort

func GetTcpPort() (PortResult, error)

GetTcpPort gets a port for some random available address using either TCP4 or TCP6. See GetPort for more detail

func GetTcpPortForAddress

func GetTcpPortForAddress(address string) (PortResult, error)

GetTcpPortForAddress gets either a TCP4 or TCP6 port for the given address. See GetPort for more detail.

func GetUdp4Port

func GetUdp4Port() (PortResult, error)

GetUdp4Port gets a port for some random available address using UDP4. See GetPort for more detail

func GetUdp4PortForAddress

func GetUdp4PortForAddress(address string) (PortResult, error)

GetUdp4PortForAddress gets a UDP4 port for the given address. See GetPort for more detail.

func GetUdp6Port

func GetUdp6Port() (PortResult, error)

GetUdp6Port gets a port for some random available address using UDP6. See GetPort for more detail

func GetUdp6PortForAddress

func GetUdp6PortForAddress(address string) (PortResult, error)

GetUdp6PortForAddress gets a UDP6 port for the given address. See GetPort for more detail.

func GetUdpPort

func GetUdpPort() (PortResult, error)

GetUdpPort gets a port for some random available address using either UDP4 or UDP6. See GetPort for more detail

func GetUdpPortForAddress

func GetUdpPortForAddress(address string) (PortResult, error)

GetUdpPortForAddress gets either a UDP4 or UDP6 port for the given address. See GetPort for more detail.

type Protocol

type Protocol int

Protocol indicates the communication protocol (tcp or udp) and network stack (IPv4, IPv6, or OS choice) to target when finding an available port.

const (
	// TCP indicates to let the OS decide between IPv4 and IPv6 when finding
	// an open TCP based port.
	TCP Protocol = iota

	// TCP4 indicates to find an open IPv4 port.
	TCP4

	// TCP6 indicates to find an open IPv6 port.
	TCP6

	// UDP indicates to let the OS decide between IPv4 and IPv6 when finding
	// an open UDP based port.
	UDP

	// UDP4 indicates to find an open IPv4 port.
	UDP4

	// UDP6 indicates to find an open IPv6 port.
	UDP6
)