socket

package module
v0.5.1 Latest Latest
Warning

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

 Go to latest Published: Mar 15, 2024 License: MIT Imports: 14 Imported by: 12

README

socket Test Status Go Reference Go Report Card

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.

Stability

See the CHANGELOG file for a description of changes between releases.

This package only supports the two most recent major versions of Go, mirroring Go's own release policy. Older versions of Go may lack critical features and bug fixes which are necessary for this package to function correctly.

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

Constants

This section is empty.

Variables

This section is empty.

Functions

This section is empty.

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.

Many of a Conn's blocking methods support net.Conn deadlines as well as cancelation via context. Note that passing a context with a deadline set will override any of the previous deadlines set by calls to the SetDeadline family of methods.

func FileConn added in v0.2.0 

func FileConn(f *os.File, name string) (*Conn, error)

FileConn returns a copy of the network connection corresponding to the open file. It is the caller's responsibility to close the file when finished. Closing the Conn does not affect the File, and closing the File does not affect the Conn.

func New added in v0.2.3 

func New(fd int, name string) (*Conn, error)

New wraps an existing file descriptor to create a Conn. name should be a unique name for the socket type such as "netlink" or "vsock".

Most callers should use Socket or FileConn to construct a Conn. New is intended for integrating with specific system calls which provide a file descriptor that supports asynchronous I/O. The file descriptor is immediately set to nonblocking mode and registered with Go's runtime network poller for future I/O operations.

Unlike FileConn, New does not duplicate the existing file descriptor in any way. The returned Conn takes ownership of the underlying file descriptor.

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(ctx context.Context, 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.

Accept obeys context cancelation and uses the deadline set on the context to cancel accepting the next connection. If a deadline is set on ctx, this deadline will override any previous deadlines set using SetDeadline or SetReadDeadline. Upon return, the read deadline is cleared.

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) CloseRead added in v0.1.1 

func (c *Conn) CloseRead() error

CloseRead shuts down the reading side of the Conn. Most callers should just use Close.

func (*Conn) CloseWrite added in v0.1.1 

func (c *Conn) CloseWrite() error

CloseWrite shuts down the writing side of the Conn. Most callers should just use Close.

func (*Conn) Connect 

func (c *Conn) Connect(ctx context.Context, sa unix.Sockaddr) (unix.Sockaddr, error)

Connect wraps connect(2). In order to verify that the underlying socket is connected to a remote peer, Connect calls getpeername(2) and returns the unix.Sockaddr from that call.

Connect obeys context cancelation and uses the deadline set on the context to cancel connecting to a remote peer. If a deadline is set on ctx, this deadline will override any previous deadlines set using SetDeadline or SetWriteDeadline. Upon return, the write deadline is cleared.

func (*Conn) Getpeername added in v0.1.2 

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

Getpeername wraps getpeername(2).

func (*Conn) Getsockname 

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

Getsockname wraps getsockname(2).

func (*Conn) GetsockoptICMPv6Filter added in v0.5.0 

func (c *Conn) GetsockoptICMPv6Filter(level, opt int) (*unix.ICMPv6Filter, error)

GetsockoptICMPv6Filter wraps getsockopt(2) for *unix.ICMPv6Filter values.

func (*Conn) GetsockoptInt 

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

GetsockoptInt wraps getsockopt(2) for integer values.

func (*Conn) GetsockoptString added in v0.5.0 

func (c *Conn) GetsockoptString(level, opt int) (string, error)

GetsockoptString wraps getsockopt(2) for string values.

func (*Conn) GetsockoptTpacketStats added in v0.4.1 

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

GetsockoptTpacketStats wraps getsockopt(2) for unix.TpacketStats values.

func (*Conn) GetsockoptTpacketStatsV3 added in v0.4.1 

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

GetsockoptTpacketStatsV3 wraps getsockopt(2) for unix.TpacketStatsV3 values.

func (*Conn) IoctlKCMAttach added in v0.2.2 

func (c *Conn) IoctlKCMAttach(info unix.KCMAttach) error

IoctlKCMAttach wraps ioctl(2) for unix.KCMAttach values.

func (*Conn) IoctlKCMClone added in v0.2.2 

func (c *Conn) IoctlKCMClone() (*Conn, error)

IoctlKCMClone wraps ioctl(2) for unix.KCMClone values, but returns a Conn rather than a raw file descriptor.

func (*Conn) IoctlKCMUnattach added in v0.2.2 

func (c *Conn) IoctlKCMUnattach(info unix.KCMUnattach) error

IoctlKCMUnattach wraps ioctl(2) for unix.KCMUnattach values.

func (*Conn) Listen 

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

Listen wraps listen(2).

func (*Conn) PidfdGetfd added in v0.2.3 

func (c *Conn) PidfdGetfd(targetFD, flags int) (*Conn, error)

PidfdGetfd wraps pidfd_getfd(2) for a Conn which wraps a pidfd, but returns a Conn rather than a raw file descriptor.

func (*Conn) PidfdSendSignal added in v0.2.3 

func (c *Conn) PidfdSendSignal(sig unix.Signal, info *unix.Siginfo, flags int) error

PidfdSendSignal wraps pidfd_send_signal(2) for a Conn which wraps a Linux pidfd.

func (*Conn) Read 

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

Read reads 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) ReadContext added in v0.3.0 

func (c *Conn) ReadContext(ctx context.Context, b []byte) (int, error)

ReadContext reads from the underlying file descriptor with added support for context cancelation.

func (*Conn) Recvfrom 

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

Recvfrom wraps recvfrom(2).

func (*Conn) Recvmsg 

func (c *Conn) Recvmsg(ctx context.Context, 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(ctx context.Context, p, oob []byte, to unix.Sockaddr, flags int) (int, error)

Sendmsg wraps sendmsg(2).

func (*Conn) Sendto 

func (c *Conn) Sendto(ctx context.Context, p []byte, flags int, to unix.Sockaddr) 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) SetsockoptICMPv6Filter added in v0.5.0 

func (c *Conn) SetsockoptICMPv6Filter(level, opt int, filter *unix.ICMPv6Filter) error

SetsockoptICMPv6Filter wraps setsockopt(2) for *unix.ICMPv6Filter values.

func (*Conn) SetsockoptInt 

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

SetsockoptInt wraps setsockopt(2) for integer values.

func (*Conn) SetsockoptPacketMreq added in v0.2.1 

func (c *Conn) SetsockoptPacketMreq(level, opt int, mreq *unix.PacketMreq) error

SetsockoptPacketMreq wraps setsockopt(2) for unix.PacketMreq 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) SetsockoptString added in v0.5.0 

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

SetsockoptString wraps setsockopt(2) for string values.

func (*Conn) Shutdown added in v0.1.1 

func (c *Conn) Shutdown(how int) error

Shutdown wraps shutdown(2).

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) Waitid added in v0.3.0 

func (c *Conn) Waitid(idType int, info *unix.Siginfo, options int, rusage *unix.Rusage) error

Waitid wraps waitid(2).

func (*Conn) Write 

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

Write writes 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.

func (*Conn) WriteContext added in v0.3.0 

func (c *Conn) WriteContext(ctx context.Context, b []byte) (int, error)

WriteContext writes to the underlying file descriptor with added support for context cancelation.

Source Files

View all Source files

Directories

Path Synopsis
internal
sockettest
Package sockettest implements net.Listener and net.Conn types based on *socket.Conn for use in the package's tests.
 Package sockettest implements net.Listener and net.Conn types based on *socket.Conn for use in the package's tests.

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.