netdb

package module
v1.1.2 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Mar 26, 2024 License: Apache-2.0 Imports: 5 Imported by: 6

README

netdb

pkg.go.dev GitHub build and test Go Report Card Coverage

netdb provides information about TCP/IP subsystem protocols and internet services, all this in (pure) Go. By default, it uses its built-in database instead of consulting /etc/protocols, /etc/services, and /etc/ethertypes. If needed, it can also consult these files, please see the examples in the documentation.

The built-in database has been auto-generated from the etc/protocols, etc/ethertypes, and etc/services files courtesy of the netbase package of the Debian project.

This netdb package does not even try to slavishly replicate the POSIX C API; instead, it attempts to be Go-ish. For instance, the C type servent has simply become the netdb.Service type in order to avoid arcane POSIX-rooted type names.

Please refer to the reference documentation for usage examples.

Acknowledgement

In some sense, this netdb package picks up the baton from the @dominikh/go-netdb package. However, it is not a fork but was written from scratch, considering (at least some of) the advice in issue #1 of the go-netdb package.

netdb is Copyright 2021-24 Harald Albrecht, and licensed under the Apache License, Version 2.0.

Documentation

Overview

Package netdb provides information about TCP/IP subsystem protocols and internet services, as commonly stored in files /etc/protocols and /etc/services. It is a pure Go implementation.

This netdb package does not even try to slavishly replicate the POSIX C API; instead, it attempts to be Go-ish. For instance, the C type "servent" has simply become the netdb.Service type in order to avoid the arcane POSIX-rooted type names.

The netdb package defaults to looking up protocols and services information from its built-in database instead of consulting /etc/protocols and /etc/services. Additionally, it also supports reading the protocol and service descriptions from the well-known /etc/protocols and /etc/services files; please see the examples for how to access these sources.

Notes

This package bases on the file format descriptions for protocols(5) and services(5), as documented in https://man7.org/linux/man-pages/man5/protocols.5.html and https://man7.org/linux/man-pages/man5/services.5.html.

The built-in database has been auto-generated from the etc/protocols and etc/services files courtesy of the netbase package of the Debian project (https://salsa.debian.org/md/netbase).

In some sense, this netdb package picks up the baton from the https://github.com/dominikh/go-netdb package. However, it is not a fork but was written from scratch, considering (at least some of) the advice in issue #1 of the go-netdb package.

Example (EtherTypeByName)

Looks up an EtherType by its name 

package main

import (
	"fmt"

	"github.com/thediveo/netdb"
)

func main() {
	dot1q := netdb.EtherTypeByName("dot1q")
	fmt.Println(dot1q.Number)
}

Output:

33024
Example (EtherTypeByNumber)

Looks up an EtherType by its name 

package main

import (
	"fmt"

	"github.com/thediveo/netdb"
)

func main() {
	ipv4 := netdb.EtherTypeByNumber(0x0800)
	fmt.Println(ipv4.Name)
}

Output:

IPv4
Example (MergeEtc)

Where required, merges protocol and service descriptions from /etc/protocols and /etc/services with the built-in database, replacing builtin descriptions with those found in the files. 

package main

import (
	"fmt"

	"github.com/thediveo/netdb"
)

func main() {
	etcprotocols, _ := netdb.LoadProtocols("/etc/protocols")
	netdb.Protocols.MergeIndex(etcprotocols)
	etcservices, _ := netdb.LoadServices("/etc/services", netdb.Protocols)
	netdb.Services.MergeIndex(etcservices)
	dns := netdb.ServiceByName("domain", "udp")
	fmt.Printf("%s: %d via %s", dns.Name, dns.Port, dns.Protocol.Name)
}

Output:

domain: 53 via udp
Example (OnlyEtc)

Where required, uses protocol and service descriptions only from /etc/protocols and /etc/services, ignoring the builtin data completely. 

package main

import (
	"fmt"

	"github.com/thediveo/netdb"
)

func main() {
	etcprotocols, _ := netdb.LoadProtocols("/etc/protocols")
	netdb.Protocols = etcprotocols
	etcservices, _ := netdb.LoadServices("/etc/services", netdb.Protocols)
	netdb.Services = etcservices
	dns := netdb.ServiceByName("domain", "udp")
	fmt.Printf("%s: %d via %s", dns.Name, dns.Port, dns.Protocol.Name)
}

Output:

domain: 53 via udp
Example (ProtocolByName)

Look up a (TCP/IP subsystem) protocol by its name. 

package main

import (
	"fmt"

	"github.com/thediveo/netdb"
)

func main() {
	tcp := netdb.ProtocolByName("tcp")
	fmt.Println(tcp.Number)
}

Output:

6
Example (ProtocolByNumber)

Looks up a (TCP/IP subsystem) protocol by its (uint8) number. 

package main

import (
	"fmt"

	"github.com/thediveo/netdb"
)

func main() {
	udp := netdb.ProtocolByNumber(17)
	fmt.Println(udp.Name)
}

Output:

udp
Example (ServiceByName)

Look up a service by its name and protocol name. 

package main

import (
	"fmt"

	"github.com/thediveo/netdb"
)

func main() {
	dns := netdb.ServiceByName("domain", "udp")
	fmt.Println(dns.Port)
}

Output:

53
Example (ServiceByPort)

Look up a service by its port number and protocol name. 

package main

import (
	"fmt"

	"github.com/thediveo/netdb"
)

func main() {
	dns := netdb.ServiceByPort(53, "udp")
	fmt.Println(dns.Name)
}

Output:

domain

Index

Examples

Constants

This section is empty.

Variables

View Source 
var BuiltinEtherTypes []EtherType = builtinEtherTypes
View Source 
var BuiltinProtocols []Protocol = builtinProtocols
View Source 
var BuiltinServices []Service = builtinServices

Functions

This section is empty.

Types

type EtherType added in v1.1.0 

type EtherType struct {
	Name    string   // Official EtherType name.
	Number  uint16   // EtherType number value.
	Aliases []string // List of aliases.
	Comment string   // Entry comment, if present.
}

EtherType describes an Ethernet frame type/protocol used on an Ethernet network. Each EtherType entry contains a name and the two-octet (uint16) identitier. It also optionally contains name aliases as well as a comment.

On purpose, we don't stick with the stuttering POSIX C library names, but instead aim for more Go-like type names. After all, Go isn't similar to C, except for using letters, signs, and braces.

func EtherTypeByName added in v1.1.0 

func EtherTypeByName(name string) *EtherType

EtherTypeByName returns the EtherType details for the specified (native or aliased) name, or nil if not defined.

func EtherTypeByNumber added in v1.1.0 

func EtherTypeByNumber(number uint16) *EtherType

EtherTypeByNumber returns the EtherType details for the specified EtherType number, or nil if not defined.

func ParseEtherTypes added in v1.1.0 

func ParseEtherTypes(r io.Reader) ([]EtherType, error)

ParseEtherTypes parses EtherType definitions from the given Reader and returns them as a list of EtherType objects.

type EtherTypeIndex added in v1.1.0 

type EtherTypeIndex struct {
	Names   map[string]*EtherType
	Numbers map[uint16]*EtherType
}

EtherTypeIndex index the known EtherTypes by either name (native as well as aliases) and by number. 

var EtherTypes EtherTypeIndex

EtherTypes is the index of EtherType names and numbers. If left to the zero value, then it will be automatically initialized with the builtin definitions upon first use of EtherTypeByName or EtherTypeByNumber.

func LoadEtherTypes added in v1.1.0 

func LoadEtherTypes(name string) (EtherTypeIndex, error)

LoadEtherTypes returns an EtherTypeIndex object initialized from the defintions in the named file.

func NewEtherTypeIndex added in v1.1.0 

func NewEtherTypeIndex(ethertypes []EtherType) EtherTypeIndex

NewEtherTypeIndex returns an EtherTypeIndex object initialized with the specified EtherTypes.

func (*EtherTypeIndex) Merge added in v1.1.0 

func (i *EtherTypeIndex) Merge(ethertypes []EtherType)

Merge a list of EtherType descriptions into the current EtherTypes index, potentially overriding existing entries in the index in case of duplicates.

func (*EtherTypeIndex) MergeIndex added in v1.1.0 

func (i *EtherTypeIndex) MergeIndex(eti EtherTypeIndex)

MergeIndex merges another EtherTypeIndex into the current index, potentially overriding existing enties in the case of duplicates.

type Protocol 

type Protocol struct {
	Name    string   // Official protocol name.
	Number  uint8    // Protocol number.
	Aliases []string // List of aliases.
}

Protocol describes a network communications protocol by its native name and official protocol number as appearing within IP headers, with optional alias names.

According to http://www.iana.org/assignments/protocol-numbers/protocol-numbers.xhtml the Assigned Internet Protocol Numbers are 8 bit (unsigned) numbers.

On purpose, we don't stick with the stuttering POSIX C library names, but instead aim for more Go-like type names. After all, Go isn't similar to C, except for using letters, signs, and braces.

func ParseProtocols 

func ParseProtocols(r io.Reader) ([]Protocol, error)

ParseProtocols parses Internet protocol definitions for the TCP/IP subsystem from the given Reader and returns them as a list of Protcol(s).

func ProtocolByName 

func ProtocolByName(name string) *Protocol

ProtocolByName returns the Protocol details for the specified (alias) name, or nil if not defined.

func ProtocolByNumber 

func ProtocolByNumber(number uint8) *Protocol

ProtocolByNumber returns the Protocol details for the specified protocol number, or nil if not defined.

type ProtocolIndex 

type ProtocolIndex struct {
	Names   map[string]*Protocol // Index by protocol name, including aliases.
	Numbers map[uint8]*Protocol  // Index by protocol number.
}

ProtocolIndex indexes the known network communication protocols by either name (native as well as aliases) and by number. 

var Protocols ProtocolIndex

Protocols is the index of protocol names and numbers. If left to the zero value then it will be automatically initialized with the builtin definitions upon first use of ProtocolByName or ProtocolByNumber.

func LoadProtocols 

func LoadProtocols(name string) (ProtocolIndex, error)

LoadProtocols returns a ProtocolIndex object initialized from the definitions in the named file.

func NewProtocolIndex 

func NewProtocolIndex(protos []Protocol) ProtocolIndex

NewProtocolIndex returns a ProtocolsIndex object initialized with the specified protocols.

func (*ProtocolIndex) Merge 

func (i *ProtocolIndex) Merge(protos []Protocol)

Merge a list of Protocol descriptions into the current Protocols index, potentially overriding existing entries in the index in case of duplicates.

func (*ProtocolIndex) MergeIndex 

func (i *ProtocolIndex) MergeIndex(pi ProtocolIndex)

MergeIndex merges another ProtocolIndex into the current index, potentially overriding existing entries in case of duplicates.

type Service 

type Service struct {
	Name         string    // Official service name.
	Port         int       // Transport port number.
	ProtocolName string    // Name of protocol to use.
	Protocol     *Protocol // Protocol details, if known.
	Aliases      []string  // List of service name aliases.
}

Service describes a network service by its official service name, port number and network protocol, with optional service alias names.

On purpose, we don't stick with the stuttering POSIX C library names, but instead aim for more Go-like type names. After all, Go isn't similar to C, except for using letters, signs, and braces.

func ParseServices 

func ParseServices(r io.Reader, p ProtocolIndex) ([]Service, error)

ParseServices parses network service definitions from the given Reader and returns them as a list of Service(s).

func ServiceByName 

func ServiceByName(name string, protocol string) *Service

ServiceByName returns the Service details for the specified (alias) name and (optional) protocol name, or nil if not defined.

func ServiceByPort 

func ServiceByPort(port int, protocol string) *Service

ServiceByPort returns the Service details for the specified port number and (optional) protocol name, or nil if not defined.

type ServiceIndex 

type ServiceIndex struct {
	Names map[ServiceProtocol]*Service // Index by service name and protocol name.
	Ports map[ServicePort]*Service     // Index by port number.
}

ServiceIndex indexes the known network services by either (alias) name or by transport port number. 

var Services ServiceIndex

Services is the index of service names and protocols. If left to the zero value then it will be automatically initialized with the builtin definitions upon first use of ServiceByName or ServiceByPort.

func LoadServices 

func LoadServices(name string, protos ProtocolIndex) (ServiceIndex, error)

LoadServices returns a ServiceIndex object initialized from the definitions in the named file.

func NewServiceIndex 

func NewServiceIndex(services []Service) ServiceIndex

NewServiceIndex returns a Services index object initialized with the specified services.

func (*ServiceIndex) ByName 

func (i *ServiceIndex) ByName(name string, protocol string) *Service

ByName returns the named Service for the given protocol, or nil if not found. If the protocol is the zero value ("") then the "first" Service matching the name is returned, where "first" refers to the order in which the services were originally described in a list of services, such as /etc/services.

func (*ServiceIndex) ByPort 

func (i *ServiceIndex) ByPort(port int, protocol string) *Service

ByPort returns the service for the given port and protocol, or nil if not found. If the protocol is the zero value ("") then the "first" Service matching the name is returned, where "first" refers to the order in which the services were originally described in a list of services, such as /etc/services.

func (*ServiceIndex) Merge 

func (i *ServiceIndex) Merge(services []Service)

Merge a list of service descriptions into the current Services index, potentially overriding existing entries in the index in case of duplicates.

func (*ServiceIndex) MergeIndex 

func (i *ServiceIndex) MergeIndex(si ServiceIndex)

MergeIndex merges another ServiceIndex into the current index, potentially overriding existing entries in case of duplicates.

type ServicePort 

type ServicePort struct {
	Port     int    // Transport port number.
	Protocol string // Protocol name; might be zero.
}

ServicePort represents a Service index key.

type ServiceProtocol 

type ServiceProtocol struct {
	Name     string // Service name.
	Protocol string // Protocol name; might be zero.
}

ServiceProtocol represents a Service index key.

Source Files

View all Source files

Directories

Path Synopsis
internal
gen

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.