import "toolman.org/net/conduit"
go get toolman.org/net/conduit
conduit.go errors.go receive.go send.go
type Conduit struct {
// contains filtered or unexported fields
}
A Conduit is a mechanism for transfering open file descriptors between cooperating processes. Transfers can take place over an os.File or net.Conn but ultimately the transport descriptor must manifest as a socket capable of carrying out-of-band control messages.
func FromConn(conn net.Conn) (*Conduit, error)
FromConn creates a new Conduit from the provided net.Conn. The underlying type for the provided Conn must be one having a method with the signature "File() (*os.File, error)". If not, a conduit.Error of type ErrNoFD will be returned.
A cloned os.File object is created by FromConn. If this cloning fails, a conduit.Error of type ErrBadClone} will be returned. Since a clone is being created, you should be sure to call Close to avoid leaking a file descriptor.
func FromFile(f *os.File) *Conduit
FromFile creates a new Conduit from the provided os.File.
func New(fd uintptr, name string) *Conduit
New creates a new Conduit. The provided file descriptor is the transport over which other open FDs will be transferred and thus must be capable of carrying out-of-band control messages. Note that this restriction is not enforced here but will instead cause later transfer actions to fail. The given name is as passed to os.NewFile.
func (c *Conduit) Close() error
Close is provided to allow the caller to close any cloned os.File objects that may have been created while constructing a Conduit. If none were created, then calling Close has no effect and will return nil. Therefore, it's a good idea to always call Close when you're done with a Conduit. Close implements io.Closer
func (c *Conduit) ReceiveConn() (net.Conn, error)
ReceiveConn returns a net.Conn associated with the open file descriptor received through the Conduit.
In addition to the errors described for ReceiveFD, the following are also possible. The act of receiving the Conn requires a clone of an underlying File object. If this fails, a conduit.Error of type ErrBadClone is returned. Prior to returning the Conn, the original File will be closed. If this close results in an error, a conduit.Error of type ErrFailedClosed is returned.
func (c *Conduit) ReceiveFD() (uintptr, error)
ReceiveFD receives and returns a single open file descriptor from the Conduit along with a nil error. If an error is returned it will be a conduit.Error with its type set according to the following conditions.
ErrFailedTransfer: if the message cannot be recieved.
ControlMessageError: if the control message cannot be parsed, more than
one control message is sent or more than one file descriptor is
transfered.
func (c *Conduit) ReceiveFile() (*os.File, error)
ReceiveFile returns a *os.File associated with the open file descripted recevied through the Conduit. The provided name will be attached to the now File object. See ReceiveFD() for a discussion of possible error conditions.
func (c *Conduit) TransferConn(conn net.Conn) error
TransferConn send the open file descriptor associated with conn through the Conduit. If succesfully transfered, conn will be closed and may no longer be used by the caller. Nil is returned on success.
If conn's underlying type provides no way to discern its file descriptor, a conduit.Error of type ErrNoFD is returned. As part of the transfer, an os.File object is cloned from conn. If this fails, a conduit.Error of type ErrBadClone is returned. Note that both conn and its clone are closed upon a successful transfer.
func (c *Conduit) TransferFD(fd uintptr) error
TransferFD sends the open file descriptor fd through the Conduit. If successfully transfered, fd will be closed and may no longer be used by the caller. On success, nil is returned.
If an error is returned, it will be of type conduit.Error.
func (c *Conduit) TransferFile(f *os.File) error
TransferFile send the open file descriptor associated with f through the Conduit. If succesfully transfered, f will be closed and may no longer be used by the caller. On success, nil is returned.
If an error is returned, it will be of type conduit.Error.
type ErrType int
ErrType differentiates disparate Conduit errors.
const (
// ErrUnknown is an unknown error type; there are no errors of this type
// (i.e. if you get one of these it's a bug)
ErrUnknown ErrType = iota
// ErrNoFD is returned when a Conduit method is unable to extrapolate an
// underlying file descriptor from one of its arguments.
ErrNoFD
// ErrFailedTransfer is returned when a file descriptor transfer fails.
ErrFailedTransfer
// ErrFailedClose is returned when a Close method fails.
ErrFailedClose
// ErrBadClone is returned on a failed attempt to clone an os.File object.
ErrBadClone
// ErrBadCtrlMesg is returned for low level errors while constructing,
// sending or receiving the out-of-band control message used to transfer
// a file descriptor.
ErrBadCtrlMesg
)
type Error struct {
// contains filtered or unexported fields
}
Error encapsulates a conduit related error providing a Type method to discern the type of error.
func (e *Error) Type() ErrType
Type returns the conduit related error type indicated by the returned ErrType value.
FAQs
Unknown package
Did you know?
Socket for GitHub automatically highlights issues in each pull request and monitors the health of all your open source dependencies. Discover the contents of your packages and block harmful activity before you install or update your dependencies.
Security News
Chrome 144 introduces the Temporal API, a modern approach to date and time handling designed to fix long-standing issues with JavaScript’s Date object.
Research
Five coordinated Chrome extensions enable session hijacking and block security controls across enterprise HR and ERP platforms.
Research
Node.js patched a crash bug where AsyncLocalStorage could cause stack overflows to bypass error handlers and terminate production servers.