A Config contains options for a Conn.
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 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.
type Conn struct {
// contains filtered or unexported fields
}
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(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(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 (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 (c *Conn) Bind(sa unix.Sockaddr) error
Bind wraps bind(2).
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 (c *Conn) CloseRead() error
CloseRead shuts down the reading side of the Conn. Most callers should just use Close.
func (c *Conn) CloseWrite() error
CloseWrite shuts down the writing side of the Conn. Most callers should just use Close.
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 (c *Conn) Getpeername() (unix.Sockaddr, error)
Getpeername wraps getpeername(2).
func (c *Conn) Getsockname() (unix.Sockaddr, error)
Getsockname wraps getsockname(2).
func (c *Conn) GetsockoptInt(level, opt int) (int, error)
GetsockoptInt wraps getsockopt(2) for integer values.
func (c *Conn) GetsockoptTpacketStats(level, name int) (*unix.TpacketStats, error)
GetsockoptTpacketStats wraps getsockopt(2) for unix.TpacketStats values.
func (c *Conn) GetsockoptTpacketStatsV3(level, name int) (*unix.TpacketStatsV3, error)
GetsockoptTpacketStatsV3 wraps getsockopt(2) for unix.TpacketStatsV3 values.
func (c *Conn) IoctlKCMAttach(info unix.KCMAttach) error
IoctlKCMAttach wraps ioctl(2) for unix.KCMAttach values.
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 (c *Conn) IoctlKCMUnattach(info unix.KCMUnattach) error
IoctlKCMUnattach wraps ioctl(2) for unix.KCMUnattach values.
func (c *Conn) Listen(n int) error
Listen wraps listen(2).
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 (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 (c *Conn) Read(b []byte) (int, error)
Read reads directly from the underlying file descriptor.
func (c *Conn) ReadBuffer() (int, error)
ReadBuffer gets the size of the operating system's receive buffer associated with the Conn.
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 (c *Conn) Recvfrom(ctx context.Context, p []byte, flags int) (int, unix.Sockaddr, error)
Recvfrom wraps recvfrom(2).
func (c *Conn) Recvmsg(ctx context.Context, p, oob []byte, flags int) (int, int, int, unix.Sockaddr, error)
Recvmsg wraps recvmsg(2).
func (c *Conn) RemoveBPF() error
RemoveBPF removes a BPF filter from a Conn.
func (c *Conn) Sendmsg(ctx context.Context, p, oob []byte, to unix.Sockaddr, flags int) (int, error)
Sendmsg wraps sendmsg(2).
func (c *Conn) Sendto(ctx context.Context, p []byte, flags int, to unix.Sockaddr) error
Sendto wraps sendto(2).
func (c *Conn) SetBPF(filter []bpf.RawInstruction) error
SetBPF attaches an assembled BPF program to a Conn.
func (c *Conn) SetDeadline(t time.Time) error
SetDeadline sets both the read and write deadlines associated with the Conn.
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 (c *Conn) SetReadDeadline(t time.Time) error
SetReadDeadline sets the read deadline associated with the Conn.
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 (c *Conn) SetWriteDeadline(t time.Time) error
SetWriteDeadline sets the write deadline associated with the Conn.
func (c *Conn) SetsockoptInt(level, opt, value int) error
SetsockoptInt wraps setsockopt(2) for integer values.
func (c *Conn) SetsockoptPacketMreq(level, opt int, mreq *unix.PacketMreq) error
SetsockoptPacketMreq wraps setsockopt(2) for unix.PacketMreq values.
func (c *Conn) SetsockoptSockFprog(level, opt int, fprog *unix.SockFprog) error
SetsockoptSockFprog wraps setsockopt(2) for unix.SockFprog values.
func (c *Conn) Shutdown(how int) error
Shutdown wraps shutdown(2).
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 (c *Conn) Waitid(idType int, info *unix.Siginfo, options int, rusage *unix.Rusage) error
Waitid wraps waitid(2).
func (c *Conn) Write(b []byte) (int, error)
Write writes directly to the underlying file descriptor.
func (c *Conn) WriteBuffer() (int, error)
WriteBuffer gets the size of the operating system's transmit buffer associated with the Conn.
func (c *Conn) WriteContext(ctx context.Context, b []byte) (int, error)
WriteContext writes to the underlying file descriptor with added support for context cancelation.
| Name | Synopsis |
|---|---|
| .. | |