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.