socket

README

socket

Package socket provides a low-level network connection type which integrates with Go's runtime network poller to provide asynchronous I/O and deadline support. MIT Licensed.

This package focuses on UNIX-like operating systems which make use of BSD sockets system call APIs. It is meant to be used as a foundation for the creation of operating system-specific socket packages, for socket families such as Linux's AF_NETLINK, AF_PACKET, or AF_VSOCK. This package should not be used directly in end user applications.

Any use of package socket should be guarded by build tags, as one would also use when importing the syscall or golang.org/x/sys packages.

Documentation

Overview

Package socket provides a low-level network connection type which integrates with Go's runtime network poller to provide asynchronous I/O and deadline support.

This package focuses on UNIX-like operating systems which make use of BSD sockets system call APIs. It is meant to be used as a foundation for the creation of operating system-specific socket packages, for socket families such as Linux's AF_NETLINK, AF_PACKET, or AF_VSOCK. This package should not be used directly in end user applications.

Any use of package socket should be guarded by build tags, as one would also use when importing the syscall or golang.org/x/sys packages.

Index

• type Config
• type Conn
  • func Socket(domain, typ, proto int, name string, cfg *Config) (*Conn, error)
  • func (c *Conn) Accept(flags int) (*Conn, unix.Sockaddr, error)
  • func (c *Conn) Bind(sa unix.Sockaddr) error
  • func (c *Conn) Close() error
  • func (c *Conn) Connect(sa unix.Sockaddr) error
  • func (c *Conn) GetSockoptTpacketStats(level, name int) (*unix.TpacketStats, error)
  • func (c *Conn) GetSockoptTpacketStatsV3(level, name int) (*unix.TpacketStatsV3, error)
  • func (c *Conn) Getsockname() (unix.Sockaddr, error)
  • func (c *Conn) GetsockoptInt(level, opt int) (int, error)
  • func (c *Conn) Listen(n int) error
  • func (c *Conn) Read(b []byte) (int, error)
  • func (c *Conn) ReadBuffer() (int, error)
  • func (c *Conn) Recvfrom(p []byte, flags int) (int, unix.Sockaddr, error)
  • func (c *Conn) Recvmsg(p, oob []byte, flags int) (int, int, int, unix.Sockaddr, error)
  • func (c *Conn) RemoveBPF() error
  • func (c *Conn) Sendmsg(p, oob []byte, to unix.Sockaddr, flags int) error
  • func (c *Conn) Sendto(b []byte, to unix.Sockaddr, flags int) error
  • func (c *Conn) SetBPF(filter []bpf.RawInstruction) error
  • func (c *Conn) SetDeadline(t time.Time) error
  • func (c *Conn) SetReadBuffer(bytes int) error
  • func (c *Conn) SetReadDeadline(t time.Time) error
  • func (c *Conn) SetWriteBuffer(bytes int) error
  • func (c *Conn) SetWriteDeadline(t time.Time) error
  • func (c *Conn) SetsockoptInt(level, opt, value int) error
  • func (c *Conn) SetsockoptSockFprog(level, opt int, fprog *unix.SockFprog) error
  • func (c *Conn) SyscallConn() (syscall.RawConn, error)
  • func (c *Conn) Write(b []byte) (int, error)
  • func (c *Conn) WriteBuffer() (int, error)

Types

type Config

type Config struct {
	// NetNS specifies the Linux network namespace the Conn will operate in.
	// This option is unsupported on other operating systems.
	//
	// If set (non-zero), Conn will enter the specified network namespace and an
	// error will occur in Socket if the operation fails.
	//
	// If not set (zero), a best-effort attempt will be made to enter the
	// network namespace of the calling thread: this means that any changes made
	// to the calling thread's network namespace will also be reflected in Conn.
	// If this operation fails (due to lack of permissions or because network
	// namespaces are disabled by kernel configuration), Socket will not return
	// an error, and the Conn will operate in the default network namespace of
	// the process. This enables non-privileged use of Conn in applications
	// which do not require elevated privileges.
	//
	// Entering a network namespace is a privileged operation (root or
	// CAP_SYS_ADMIN are required), and most applications should leave this set
	// to 0.
	NetNS int
}

A Config contains options for a Conn.

type Conn

type Conn struct {
	// contains filtered or unexported fields
}

A Conn is a low-level network connection which integrates with Go's runtime network poller to provide asynchronous I/O and deadline support.

func Socket

func Socket(domain, typ, proto int, name string, cfg *Config) (*Conn, error)

Socket wraps the socket(2) system call to produce a Conn. domain, typ, and proto are passed directly to socket(2), and name should be a unique name for the socket type such as "netlink" or "vsock".

The cfg parameter specifies optional configuration for the Conn. If nil, no additional configuration will be applied.

If the operating system supports SOCK_CLOEXEC and SOCK_NONBLOCK, they are automatically applied to typ to mirror the standard library's socket flag behaviors.

func (*Conn) Accept

func (c *Conn) Accept(flags int) (*Conn, unix.Sockaddr, error)

Accept wraps accept(2) or accept4(2) depending on the operating system, but returns a Conn for the accepted connection rather than a raw file descriptor.

If the operating system supports accept4(2) (which allows flags), SOCK_CLOEXEC and SOCK_NONBLOCK are automatically applied to flags to mirror the standard library's socket flag behaviors.

If the operating system only supports accept(2) (which does not allow flags) and flags is not zero, an error will be returned.

func (*Conn) Bind

func (c *Conn) Bind(sa unix.Sockaddr) error

Bind wraps bind(2).

func (*Conn) Close

func (c *Conn) Close() error

Close closes the underlying file descriptor for the Conn, which also causes all in-flight I/O operations to immediately unblock and return errors. Any subsequent uses of Conn will result in EBADF.

func (*Conn) Connect

func (c *Conn) Connect(sa unix.Sockaddr) error

Connect wraps connect(2).

func (*Conn) GetSockoptTpacketStats

func (c *Conn) GetSockoptTpacketStats(level, name int) (*unix.TpacketStats, error)

GetSockoptTpacketStats wraps getsockopt(2) for getting TpacketStats

func (*Conn) GetSockoptTpacketStatsV3

func (c *Conn) GetSockoptTpacketStatsV3(level, name int) (*unix.TpacketStatsV3, error)

GetSockoptTpacketStatsV3 wraps getsockopt(2) for getting TpacketStatsV3

func (*Conn) Getsockname

func (c *Conn) Getsockname() (unix.Sockaddr, error)

Getsockname wraps getsockname(2).

func (*Conn) GetsockoptInt

func (c *Conn) GetsockoptInt(level, opt int) (int, error)

GetsockoptInt wraps getsockopt(2) for integer values.

func (*Conn) Listen

func (c *Conn) Listen(n int) error

Listen wraps listen(2).

func (*Conn) Read

func (c *Conn) Read(b []byte) (int, error)

Read implements io.Reader by reading directly from the underlying file descriptor.

func (*Conn) ReadBuffer

func (c *Conn) ReadBuffer() (int, error)

ReadBuffer gets the size of the operating system's receive buffer associated with the Conn.

func (*Conn) Recvfrom

func (c *Conn) Recvfrom(p []byte, flags int) (int, unix.Sockaddr, error)

Recvfrom wraps recvfrom(2)

func (*Conn) Recvmsg

func (c *Conn) Recvmsg(p, oob []byte, flags int) (int, int, int, unix.Sockaddr, error)

Recvmsg wraps recvmsg(2).

func (*Conn) RemoveBPF

func (c *Conn) RemoveBPF() error

RemoveBPF removes a BPF filter from a Conn.

func (*Conn) Sendmsg

func (c *Conn) Sendmsg(p, oob []byte, to unix.Sockaddr, flags int) error

Sendmsg wraps sendmsg(2).

func (*Conn) Sendto

func (c *Conn) Sendto(b []byte, to unix.Sockaddr, flags int) error

Sendto wraps Sendto(2).

func (*Conn) SetBPF

func (c *Conn) SetBPF(filter []bpf.RawInstruction) error

SetBPF attaches an assembled BPF program to a Conn.

func (*Conn) SetDeadline

func (c *Conn) SetDeadline(t time.Time) error

SetDeadline sets both the read and write deadlines associated with the Conn.

func (*Conn) SetReadBuffer

func (c *Conn) SetReadBuffer(bytes int) error

SetReadBuffer sets the size of the operating system's receive buffer associated with the Conn.

When called with elevated privileges on Linux, the SO_RCVBUFFORCE option will be used to override operating system limits. Otherwise SO_RCVBUF is used (which obeys operating system limits).

func (*Conn) SetReadDeadline

func (c *Conn) SetReadDeadline(t time.Time) error

SetReadDeadline sets the read deadline associated with the Conn.

func (*Conn) SetWriteBuffer

func (c *Conn) SetWriteBuffer(bytes int) error

SetWriteBuffer sets the size of the operating system's transmit buffer associated with the Conn.

When called with elevated privileges on Linux, the SO_SNDBUFFORCE option will be used to override operating system limits. Otherwise SO_SNDBUF is used (which obeys operating system limits).

func (*Conn) SetWriteDeadline

func (c *Conn) SetWriteDeadline(t time.Time) error

SetWriteDeadline sets the write deadline associated with the Conn.

func (*Conn) SetsockoptInt

func (c *Conn) SetsockoptInt(level, opt, value int) error

SetsockoptInt wraps setsockopt(2) for integer values.

func (*Conn) SetsockoptSockFprog

func (c *Conn) SetsockoptSockFprog(level, opt int, fprog *unix.SockFprog) error

SetsockoptSockFprog wraps setsockopt(2) for unix.SockFprog values.

func (*Conn) SyscallConn

func (c *Conn) SyscallConn() (syscall.RawConn, error)

SyscallConn returns a raw network connection. This implements the syscall.Conn interface.

SyscallConn is intended for advanced use cases, such as getting and setting arbitrary socket options using the socket's file descriptor. If possible, those operations should be performed using methods on Conn instead.

Once invoked, it is the caller's responsibility to ensure that operations performed using Conn and the syscall.RawConn do not conflict with each other.

func (*Conn) Write

func (c *Conn) Write(b []byte) (int, error)

Write implements io.Writer by writing directly to the underlying file descriptor.

func (*Conn) WriteBuffer

func (c *Conn) WriteBuffer() (int, error)

WriteBuffer gets the size of the operating system's transmit buffer associated with the Conn.