Documentation
¶
Overview ¶
Package unix contains the implementation of Unix endpoints.
Index ¶
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
Types ¶
type BoundEndpoint ¶
type BoundEndpoint interface {
// BidirectionalConnect establishes a bi-directional connection between two
// unix endpoints in an all-or-nothing manner. If an error occurs during
// connecting, the state of neither endpoint should be modified.
//
// In order for an endpoint to establish such a bidirectional connection
// with a BoundEndpoint, the endpoint calls the BidirectionalConnect method
// on the BoundEndpoint and sends a representation of itself (the
// ConnectingEndpoint) and a callback (returnConnect) to receive the
// connection information (Receiver and ConnectedEndpoint) upon a
// successful connect. The callback should only be called on a successful
// connect.
//
// For a connection attempt to be successful, the ConnectingEndpoint must
// be unconnected and not listening and the BoundEndpoint whose
// BidirectionalConnect method is being called must be listening.
//
// This method will return tcpip.ErrConnectionRefused on endpoints with a
// type that isn't SockStream or SockSeqpacket.
BidirectionalConnect(ep ConnectingEndpoint, returnConnect func(Receiver, ConnectedEndpoint)) *tcpip.Error
// UnidirectionalConnect establishes a write-only connection to a unix endpoint.
//
// This method will return tcpip.ErrConnectionRefused on a non-SockDgram
// endpoint.
UnidirectionalConnect() (ConnectedEndpoint, *tcpip.Error)
// Release releases any resources held by the BoundEndpoint. It must be
// called before dropping all references to a BoundEndpoint returned by a
// function.
Release()
}
A BoundEndpoint is a unix endpoint that can be connected to.
type ConnectedEndpoint ¶
type ConnectedEndpoint interface {
// Passcred implements Endpoint.Passcred.
Passcred() bool
// GetLocalAddress implements Endpoint.GetLocalAddress.
GetLocalAddress() (tcpip.FullAddress, *tcpip.Error)
// Send sends a single message. This method does not block.
//
// notify indicates if SendNotify should be called.
Send(data [][]byte, controlMessages ControlMessages, from tcpip.FullAddress) (n uintptr, notify bool, err *tcpip.Error)
// SendNotify notifies the ConnectedEndpoint of a successful Send. This
// must not be called while holding any endpoint locks.
SendNotify()
// CloseSend prevents the sending of additional Messages.
//
// After CloseSend is call, CloseNotify must also be called.
CloseSend()
// CloseNotify notifies the ConnectedEndpoint of send being closed. This
// must not be called while holding any endpoint locks.
CloseNotify()
// Writable returns if messages should be attempted to be sent. This
// includes when write has been shutdown.
Writable() bool
// EventUpdate lets the ConnectedEndpoint know that event registrations
// have changed.
EventUpdate()
// SendQueuedSize returns the total amount of data currently queued for
// sending. SendQueuedSize should return -1 if the operation isn't
// supported.
SendQueuedSize() int64
// SendMaxQueueSize returns maximum value for SendQueuedSize.
// SendMaxQueueSize should return -1 if the operation isn't supported.
SendMaxQueueSize() int64
// Release releases any resources owned by the ConnectedEndpoint. It should
// be called before droping all references to a ConnectedEndpoint.
Release()
}
A ConnectedEndpoint is an Endpoint that can be used to send Messages.
type ConnectingEndpoint ¶
type ConnectingEndpoint interface {
// ID returns the endpoint's globally unique identifier. This identifier
// must be used to determine locking order if more than one endpoint is
// to be locked in the same codepath. The endpoint with the smaller
// identifier must be locked before endpoints with larger identifiers.
ID() uint64
// Passcred implements socket.Credentialer.Passcred.
Passcred() bool
// Type returns the socket type, typically either SockStream or
// SockSeqpacket. The connection attempt must be aborted if this
// value doesn't match the ConnectableEndpoint's type.
Type() SockType
// GetLocalAddress returns the bound path.
GetLocalAddress() (tcpip.FullAddress, *tcpip.Error)
// Locker protects the following methods. While locked, only the holder of
// the lock can change the return value of the protected methods.
sync.Locker
// Connected returns true iff the ConnectingEndpoint is in the connected
// state. ConnectingEndpoints can only be connected to a single endpoint,
// so the connection attempt must be aborted if this returns true.
Connected() bool
// Listening returns true iff the ConnectingEndpoint is in the listening
// state. ConnectingEndpoints cannot make connections while listening, so
// the connection attempt must be aborted if this returns true.
Listening() bool
// WaiterQueue returns a pointer to the endpoint's waiter queue.
WaiterQueue() *waiter.Queue
}
A ConnectingEndpoint is a connectioned unix endpoint that is attempting to establish a bidirectional connection with a BoundEndpoint.
type ControlMessages ¶
type ControlMessages struct {
// Rights is a control message containing FDs.
Rights RightsControlMessage
// Credentials is a control message containing Unix credentials.
Credentials CredentialsControlMessage
}
A ControlMessages represents a collection of socket control messages.
func (*ControlMessages) Clone ¶
func (c *ControlMessages) Clone() ControlMessages
Clone clones both the credentials and the rights.
func (*ControlMessages) Empty ¶
func (c *ControlMessages) Empty() bool
Empty returns true iff the ControlMessages does not contain either credentials or rights.
func (*ControlMessages) Release ¶
func (c *ControlMessages) Release()
Release releases both the credentials and the rights.
type Credentialer ¶
type Credentialer interface {
// Passcred returns whether or not the SO_PASSCRED socket option is
// enabled on this end.
Passcred() bool
// ConnectedPasscred returns whether or not the SO_PASSCRED socket option
// is enabled on the connected end.
ConnectedPasscred() bool
}
A Credentialer is a socket or endpoint that supports the SO_PASSCRED socket option.
type CredentialsControlMessage ¶
type CredentialsControlMessage interface {
// Equals returns true iff the two messages are equal.
Equals(CredentialsControlMessage) bool
}
A CredentialsControlMessage is a control message containing Unix credentials.
type Endpoint ¶
type Endpoint interface {
Credentialer
waiter.Waitable
// Close puts the endpoint in a closed state and frees all resources
// associated with it.
Close()
// RecvMsg reads data and a control message from the endpoint. This method
// does not block if there is no data pending.
//
// creds indicates if credential control messages are requested by the
// caller. This is useful for determining if control messages can be
// coalesced. creds is a hint and can be safely ignored by the
// implementation if no coalescing is possible. It is fine to return
// credential control messages when none were requested or to not return
// credential control messages when they were requested.
//
// numRights is the number of SCM_RIGHTS FDs requested by the caller. This
// is useful if one must allocate a buffer to receive a SCM_RIGHTS message
// or determine if control messages can be coalesced. numRights is a hint
// and can be safely ignored by the implementation if the number of
// available SCM_RIGHTS FDs is known and no coalescing is possible. It is
// fine for the returned number of SCM_RIGHTS FDs to be either higher or
// lower than the requested number.
//
// If peek is true, no data should be consumed from the Endpoint. Any and
// all data returned from a peek should be available in the next call to
// RecvMsg.
//
// recvLen is the number of bytes copied into data.
//
// msgLen is the length of the read message consumed for datagram Endpoints.
// msgLen is always the same as recvLen for stream Endpoints.
RecvMsg(data [][]byte, creds bool, numRights uintptr, peek bool, addr *tcpip.FullAddress) (recvLen, msgLen uintptr, cm ControlMessages, err *tcpip.Error)
// SendMsg writes data and a control message to the endpoint's peer.
// This method does not block if the data cannot be written.
//
// SendMsg does not take ownership of any of its arguments on error.
SendMsg([][]byte, ControlMessages, BoundEndpoint) (uintptr, *tcpip.Error)
// Connect connects this endpoint directly to another.
//
// This should be called on the client endpoint, and the (bound)
// endpoint passed in as a parameter.
//
// The error codes are the same as Connect.
Connect(server BoundEndpoint) *tcpip.Error
// Shutdown closes the read and/or write end of the endpoint connection
// to its peer.
Shutdown(flags tcpip.ShutdownFlags) *tcpip.Error
// Listen puts the endpoint in "listen" mode, which allows it to accept
// new connections.
Listen(backlog int) *tcpip.Error
// Accept returns a new endpoint if a peer has established a connection
// to an endpoint previously set to listen mode. This method does not
// block if no new connections are available.
//
// The returned Queue is the wait queue for the newly created endpoint.
Accept() (Endpoint, *tcpip.Error)
// Bind binds the endpoint to a specific local address and port.
// Specifying a NIC is optional.
//
// An optional commit function will be executed atomically with respect
// to binding the endpoint. If this returns an error, the bind will not
// occur and the error will be propagated back to the caller.
Bind(address tcpip.FullAddress, commit func() *tcpip.Error) *tcpip.Error
// Type return the socket type, typically either SockStream, SockDgram
// or SockSeqpacket.
Type() SockType
// GetLocalAddress returns the address to which the endpoint is bound.
GetLocalAddress() (tcpip.FullAddress, *tcpip.Error)
// GetRemoteAddress returns the address to which the endpoint is
// connected.
GetRemoteAddress() (tcpip.FullAddress, *tcpip.Error)
// SetSockOpt sets a socket option. opt should be one of the tcpip.*Option
// types.
SetSockOpt(opt interface{}) *tcpip.Error
// GetSockOpt gets a socket option. opt should be a pointer to one of the
// tcpip.*Option types.
GetSockOpt(opt interface{}) *tcpip.Error
}
Endpoint is the interface implemented by Unix transport protocol implementations that expose functionality like sendmsg, recvmsg, connect, etc. to Unix socket implementations.
func NewConnectioned ¶
func NewConnectioned(stype SockType, uid UniqueIDProvider) Endpoint
NewConnectioned creates a new unbound connectionedEndpoint.
func NewConnectionless ¶
func NewConnectionless() Endpoint
NewConnectionless creates a new unbound dgram endpoint.
type Receiver ¶
type Receiver interface {
// Recv receives a single message. This method does not block.
//
// See Endpoint.RecvMsg for documentation on shared arguments.
//
// notify indicates if RecvNotify should be called.
Recv(data [][]byte, creds bool, numRights uintptr, peek bool) (recvLen, msgLen uintptr, cm ControlMessages, source tcpip.FullAddress, notify bool, err *tcpip.Error)
// RecvNotify notifies the Receiver of a successful Recv. This must not be
// called while holding any endpoint locks.
RecvNotify()
// CloseRecv prevents the receiving of additional Messages.
//
// After CloseRecv is called, CloseNotify must also be called.
CloseRecv()
// CloseNotify notifies the Receiver of recv being closed. This must not be
// called while holding any endpoint locks.
CloseNotify()
// Readable returns if messages should be attempted to be received. This
// includes when read has been shutdown.
Readable() bool
// RecvQueuedSize returns the total amount of data currently receivable.
// RecvQueuedSize should return -1 if the operation isn't supported.
RecvQueuedSize() int64
// RecvMaxQueueSize returns maximum value for RecvQueuedSize.
// RecvMaxQueueSize should return -1 if the operation isn't supported.
RecvMaxQueueSize() int64
// Release releases any resources owned by the Receiver. It should be
// called before droping all references to a Receiver.
Release()
}
A Receiver can be used to receive Messages.
type RightsControlMessage ¶
type RightsControlMessage interface {
// Clone returns a copy of the RightsControlMessage.
Clone() RightsControlMessage
// Release releases any resources owned by the RightsControlMessage.
Release()
}
A RightsControlMessage is a control message containing FDs.
type SockType ¶
type SockType int
A SockType is a type (as opposed to family) of sockets. These are enumerated in the syscall package as syscall.SOCK_* constants.
const ( // SockStream corresponds to syscall.SOCK_STREAM. SockStream SockType = 1 // SockDgram corresponds to syscall.SOCK_DGRAM. SockDgram SockType = 2 // SockRaw corresponds to syscall.SOCK_RAW. SockRaw SockType = 3 // SockSeqpacket corresponds to syscall.SOCK_SEQPACKET. SockSeqpacket SockType = 5 )
type UniqueIDProvider ¶
type UniqueIDProvider interface {
// UniqueID returns a new unique identifier.
UniqueID() uint64
}
UniqueIDProvider generates a sequence of unique identifiers useful for, among other things, lock ordering.
Source Files
Click to show internal directories.
Click to hide internal directories.