winio

README

go-winio

This repository contains utilities for efficiently performing Win32 IO operations in Go. Currently, this is focused on accessing named pipes and other file handles, and for using named pipes as a net transport.

This code relies on IO completion ports to avoid blocking IO on system threads, allowing Go to reuse the thread to schedule another goroutine. This limits support to Windows Vista and newer operating systems. This is similar to the implementation of network sockets in Go's net package.

Please see the LICENSE file for licensing information.

Thanks to natefinch for the inspiration for this library. See https://github.com/natefinch/npipe for another named pipe implementation.

Documentation

Index

• Constants
• Variables
• func DialPipe(path string, timeout *time.Duration) (net.Conn, error)
• func EncodeReparsePoint(rp *ReparsePoint) []byte
• func ListenPipe(path string, c *PipeConfig) (net.Listener, error)
• func LookupSidByName(name string) (sid string, err error)
• func MakeOpenFile(h syscall.Handle) (io.ReadWriteCloser, error)
• func RunWithPrivilege(name string, fn func() error) error
• func RunWithPrivileges(names []string, fn func() error) error
• func SddlToSecurityDescriptor(sddl string) ([]byte, error)
• func SecurityDescriptorToSddl(sd []byte) (string, error)
• func SetFileBasicInfo(f *os.File, bi *FileBasicInfo) error
• type AccountLookupError
  • func (e *AccountLookupError) Error() string
• type BackupFileReader
  • func NewBackupFileReader(f *os.File, includeSecurity bool) *BackupFileReader
  • func (r *BackupFileReader) Close() error
  • func (r *BackupFileReader) Read(b []byte) (int, error)
• type BackupFileWriter
  • func NewBackupFileWriter(f *os.File, includeSecurity bool) *BackupFileWriter
  • func (w *BackupFileWriter) Close() error
  • func (w *BackupFileWriter) Write(b []byte) (int, error)
• type BackupHeader
• type BackupStreamReader
  • func NewBackupStreamReader(r io.Reader) *BackupStreamReader
  • func (r *BackupStreamReader) Next() (*BackupHeader, error)
  • func (r *BackupStreamReader) Read(b []byte) (int, error)
• type BackupStreamWriter
  • func NewBackupStreamWriter(w io.Writer) *BackupStreamWriter
  • func (w *BackupStreamWriter) Write(b []byte) (int, error)
  • func (w *BackupStreamWriter) WriteHeader(hdr *BackupHeader) error
• type FileBasicInfo
  • func GetFileBasicInfo(f *os.File) (*FileBasicInfo, error)
• type PipeConfig
• type PrivilegeError
  • func (e *PrivilegeError) Error() string
• type ReparsePoint
  • func DecodeReparsePoint(b []byte) (*ReparsePoint, error)
• type SddlConversionError
  • func (e *SddlConversionError) Error() string
• type UnsupportedReparsePointError
  • func (e *UnsupportedReparsePointError) Error() string

Constants

const (
	BackupData = uint32(iota + 1)
	BackupEaData
	BackupSecurity
	BackupAlternateData
	BackupLink
	BackupPropertyData
	BackupObjectId
	BackupReparseData
	BackupSparseBlock
	BackupTxfsData

	StreamSparseAttributes = uint32(8)
)

const (
	SE_PRIVILEGE_ENABLED = 2

	ERROR_NOT_ALL_ASSIGNED syscall.Errno = 1300

	SeBackupPrivilege  = "SeBackupPrivilege"
	SeRestorePrivilege = "SeRestorePrivilege"
)

Variables

var (
	ErrFileClosed = errors.New("file has already been closed")
	ErrTimeout    = &timeoutError{}
)

var (
	// ErrPipeListenerClosed is returned for pipe operations on listeners that have been closed.
	// This error should match net.errClosing since docker takes a dependency on its text.
	ErrPipeListenerClosed = errors.New("use of closed network connection")
)

Functions

func DialPipe

func DialPipe(path string, timeout *time.Duration) (net.Conn, error)

DialPipe connects to a named pipe by path, timing out if the connection takes longer than the specified duration. If timeout is nil, then the timeout is the default timeout established by the pipe server.

func EncodeReparsePoint

func EncodeReparsePoint(rp *ReparsePoint) []byte

EncodeReparsePoint encodes a Win32 REPARSE_DATA_BUFFER structure describing a symlink or mount point.

func ListenPipe

func ListenPipe(path string, c *PipeConfig) (net.Listener, error)

ListenPipe creates a listener on a Windows named pipe path, e.g. \\.\pipe\mypipe. The pipe must not already exist.

func LookupSidByName

func LookupSidByName(name string) (sid string, err error)

LookupSidByName looks up the SID of an account by name

func MakeOpenFile

func MakeOpenFile(h syscall.Handle) (io.ReadWriteCloser, error)

func RunWithPrivilege

func RunWithPrivilege(name string, fn func() error) error

func RunWithPrivileges

func RunWithPrivileges(names []string, fn func() error) error

func SddlToSecurityDescriptor

func SddlToSecurityDescriptor(sddl string) ([]byte, error)

func SecurityDescriptorToSddl

func SecurityDescriptorToSddl(sd []byte) (string, error)

func SetFileBasicInfo

func SetFileBasicInfo(f *os.File, bi *FileBasicInfo) error

Types

type AccountLookupError

type AccountLookupError struct {
	Name string
	Err  error
}

func (*AccountLookupError) Error

func (e *AccountLookupError) Error() string

type BackupFileReader

type BackupFileReader struct {
	// contains filtered or unexported fields
}

BackupFileReader provides an io.ReadCloser interface on top of the BackupRead Win32 API.

func NewBackupFileReader

func NewBackupFileReader(f *os.File, includeSecurity bool) *BackupFileReader

NewBackupFileReader returns a new BackupFileReader from a file handle. If includeSecurity is true, Read will attempt to read the security descriptor of the file.

func (*BackupFileReader) Close

func (r *BackupFileReader) Close() error

Close frees Win32 resources associated with the BackupFileReader. It does not close the underlying file.

func (*BackupFileReader) Read

func (r *BackupFileReader) Read(b []byte) (int, error)

Read reads a backup stream from the file by calling the Win32 API BackupRead().

type BackupFileWriter

type BackupFileWriter struct {
	// contains filtered or unexported fields
}

BackupFileWriter provides an io.WriteCloser interface on top of the BackupWrite Win32 API.

func NewBackupFileWriter

func NewBackupFileWriter(f *os.File, includeSecurity bool) *BackupFileWriter

NewBackupFileWrtier returns a new BackupFileWriter from a file handle. If includeSecurity is true, Write() will attempt to restore the security descriptor from the stream.

func (*BackupFileWriter) Close

func (w *BackupFileWriter) Close() error

Close frees Win32 resources associated with the BackupFileWriter. It does not close the underlying file.

func (*BackupFileWriter) Write

func (w *BackupFileWriter) Write(b []byte) (int, error)

Write restores a portion of the file using the provided backup stream.

type BackupHeader

type BackupHeader struct {
	Id         uint32 // The backup stream ID
	Attributes uint32 // Stream attributes
	Size       int64  // The size of the stream in bytes
	Name       string // The name of the stream (for BackupAlternateData only).
	Offset     int64  // The offset of the stream in the file (for BackupSparseBlock only).
}

BackupHeader represents a backup stream of a file.

type BackupStreamReader

type BackupStreamReader struct {
	// contains filtered or unexported fields
}

BackupStreamReader reads from a stream produced by the BackupRead Win32 API and produces a series of BackupHeader values.

func NewBackupStreamReader

func NewBackupStreamReader(r io.Reader) *BackupStreamReader

NewBackupStreamReader produces a BackupStreamReader from any io.Reader.

func (*BackupStreamReader) Next

func (r *BackupStreamReader) Next() (*BackupHeader, error)

Next returns the next backup stream and prepares for calls to Write(). It skips the remainder of the current stream if it was not completely read.

func (*BackupStreamReader) Read

func (r *BackupStreamReader) Read(b []byte) (int, error)

Read reads from the current backup stream.

type BackupStreamWriter

type BackupStreamWriter struct {
	// contains filtered or unexported fields
}

BackupStreamWriter writes a stream compatible with the BackupWrite Win32 API.

func NewBackupStreamWriter

func NewBackupStreamWriter(w io.Writer) *BackupStreamWriter

NewBackupStreamWriter produces a BackupStreamWriter on top of an io.Writer.

func (*BackupStreamWriter) Write

func (w *BackupStreamWriter) Write(b []byte) (int, error)

Write writes to the current backup stream.

func (*BackupStreamWriter) WriteHeader

func (w *BackupStreamWriter) WriteHeader(hdr *BackupHeader) error

WriteHeader writes the next backup stream header and prepares for calls to Write().

type FileBasicInfo

type FileBasicInfo struct {
	CreationTime, LastAccessTime, LastWriteTime, ChangeTime syscall.Filetime
	FileAttributes                                          uintptr // includes padding
}

func GetFileBasicInfo

func GetFileBasicInfo(f *os.File) (*FileBasicInfo, error)

type PipeConfig

type PipeConfig struct {
	// SecurityDescriptor contains a Windows security descriptor in SDDL format.
	SecurityDescriptor string

	// MessageMode determines whether the pipe is in byte or message mode. In either
	// case the pipe is read in byte mode by default. The only practical difference in
	// this implementation is that CloseWrite() is only supported for message mode pipes;
	// CloseWrite() is implemented as a zero-byte write, but zero-byte writes are only
	// transferred to the reader (and returned as io.EOF in this implementation)
	// when the pipe is in message mode.
	MessageMode bool

	// InputBufferSize specifies the size the input buffer, in bytes.
	InputBufferSize int32

	// OutputBufferSize specifies the size the input buffer, in bytes.
	OutputBufferSize int32
}

PipeConfig contain configuration for the pipe listener.

type PrivilegeError

type PrivilegeError struct {
	// contains filtered or unexported fields
}

func (*PrivilegeError) Error

func (e *PrivilegeError) Error() string

type ReparsePoint

type ReparsePoint struct {
	Target       string
	IsMountPoint bool
}

ReparsePoint describes a Win32 symlink or mount point.

func DecodeReparsePoint

func DecodeReparsePoint(b []byte) (*ReparsePoint, error)

DecodeReparsePoint decodes a Win32 REPARSE_DATA_BUFFER structure containing either a symlink or a mount point.

type SddlConversionError

type SddlConversionError struct {
	Sddl string
	Err  error
}

func (*SddlConversionError) Error

func (e *SddlConversionError) Error() string

type UnsupportedReparsePointError

type UnsupportedReparsePointError struct {
	Tag uint32
}

UnsupportedReparsePointError is returned when trying to decode a non-symlink or mount point reparse point.

func (*UnsupportedReparsePointError) Error

func (e *UnsupportedReparsePointError) Error() string