package hcs

import "github.com/Microsoft/hcsshim/internal/hcs"

Index

Variables 

var (
	// ErrComputeSystemDoesNotExist is an error encountered when the container being operated on no longer exists
	ErrComputeSystemDoesNotExist = syscall.Errno(0xc037010e)

	// ErrElementNotFound is an error encountered when the object being referenced does not exist
	ErrElementNotFound = syscall.Errno(0x490)

	// ErrElementNotFound is an error encountered when the object being referenced does not exist
	ErrNotSupported = syscall.Errno(0x32)

	// ErrInvalidData is an error encountered when the request being sent to hcs is invalid/unsupported
	// decimal -2147024883 / hex 0x8007000d
	ErrInvalidData = syscall.Errno(0xd)

	// ErrHandleClose is an error encountered when the handle generating the notification being waited on has been closed
	ErrHandleClose = errors.New("hcsshim: the handle generating this notification has been closed")

	// ErrAlreadyClosed is an error encountered when using a handle that has been closed by the Close method
	ErrAlreadyClosed = errors.New("hcsshim: the handle has already been closed")

	// ErrInvalidNotificationType is an error encountered when an invalid notification type is used
	ErrInvalidNotificationType = errors.New("hcsshim: invalid notification type")

	// ErrInvalidProcessState is an error encountered when the process is not in a valid state for the requested operation
	ErrInvalidProcessState = errors.New("the process is in an invalid state for the attempted operation")

	// ErrTimeout is an error encountered when waiting on a notification times out
	ErrTimeout = errors.New("hcsshim: timeout waiting for notification")

	// ErrUnexpectedContainerExit is the error encountered when a container exits while waiting for
	// a different expected notification
	ErrUnexpectedContainerExit = errors.New("unexpected container exit")

	// ErrUnexpectedProcessAbort is the error encountered when communication with the compute service
	// is lost while waiting for a notification
	ErrUnexpectedProcessAbort = errors.New("lost communication with compute service")

	// ErrUnexpectedValue is an error encountered when hcs returns an invalid value
	ErrUnexpectedValue = errors.New("unexpected value returned from hcs")

	// ErrOperationDenied is an error when hcs attempts an operation that is explicitly denied
	ErrOperationDenied = errors.New("operation denied")

	// ErrVmcomputeAlreadyStopped is an error encountered when a shutdown or terminate request is made on a stopped container
	ErrVmcomputeAlreadyStopped = syscall.Errno(0xc0370110)

	// ErrVmcomputeOperationPending is an error encountered when the operation is being completed asynchronously
	ErrVmcomputeOperationPending = syscall.Errno(0xC0370103)

	// ErrVmcomputeOperationInvalidState is an error encountered when the compute system is not in a valid state for the requested operation
	ErrVmcomputeOperationInvalidState = syscall.Errno(0xc0370105)

	// ErrProcNotFound is an error encountered when a procedure look up fails.
	ErrProcNotFound = syscall.Errno(0x7f)

	// ErrVmcomputeOperationAccessIsDenied is an error which can be encountered when enumerating compute systems in RS1/RS2
	// builds when the underlying silo might be in the process of terminating. HCS was fixed in RS3.
	ErrVmcomputeOperationAccessIsDenied = syscall.Errno(0x5)

	// ErrVmcomputeInvalidJSON is an error encountered when the compute system does not support/understand the messages sent by management
	ErrVmcomputeInvalidJSON = syscall.Errno(0xc037010d)

	// ErrVmcomputeUnknownMessage is an error encountered guest compute system doesn't support the message
	ErrVmcomputeUnknownMessage = syscall.Errno(0xc037010b)

	// ErrVmcomputeUnexpectedExit is an error encountered when the compute system terminates unexpectedly
	ErrVmcomputeUnexpectedExit = syscall.Errno(0xC0370106)

	// ErrNotSupported is an error encountered when hcs doesn't support the request
	ErrPlatformNotSupported = errors.New("unsupported platform request")

	// ErrProcessAlreadyStopped is returned by hcs if the process we're trying to kill has already been stopped.
	ErrProcessAlreadyStopped = syscall.Errno(0x8037011f)

	// ErrInvalidHandle is an error that can be encountered when querying the properties of a compute system when the handle to that
	// compute system has already been closed.
	ErrInvalidHandle = syscall.Errno(0x6)
)

Functions

func CreateNTFSVHD 

func CreateNTFSVHD(ctx context.Context, vhdPath string, sizeGB uint32) (err error)

CreateNTFSVHD creates a VHD formatted with NTFS of size `sizeGB` at the given `vhdPath`.

func GetComputeSystems 

func GetComputeSystems(ctx context.Context, q schema1.ComputeSystemQuery) ([]schema1.ContainerProperties, error)

GetComputeSystems gets a list of the compute systems on the system that match the query

func GetServiceProperties 

func GetServiceProperties(ctx context.Context, q hcsschema.PropertyQuery) (*hcsschema.ServiceProperties, error)

GetServiceProperties returns properties of the host compute service.

func IsAccessIsDenied 

func IsAccessIsDenied(err error) bool

IsAccessIsDenied returns true when err is caused by `ErrVmcomputeOperationAccessIsDenied`.

func IsAlreadyClosed 

func IsAlreadyClosed(err error) bool

IsAlreadyClosed checks if an error is caused by the Container or Process having been already closed by a call to the Close() method.

func IsAlreadyStopped 

func IsAlreadyStopped(err error) bool

IsAlreadyStopped returns a boolean indicating whether the error is caused by a Container or Process being already stopped. Note: Currently, ErrElementNotFound can mean that a Process has either already exited, or does not exist. Both IsAlreadyStopped and IsNotExist will currently return true when the error is ErrElementNotFound.

func IsAny 

func IsAny(err error, targets ...error) bool

IsAny is a vectorized version of errors.Is, it returns true if err is one of targets.

func IsErrorInvalidHandle 

func IsErrorInvalidHandle(err error) bool

IsErrorInvalidHandle checks whether the error is the result of an operation carried out on a handle that is invalid/closed. This error popped up while trying to query stats on a container in the process of being stopped.

func IsNotExist 

func IsNotExist(err error) bool

IsNotExist checks if an error is caused by the Container or Process not existing. Note: Currently, ErrElementNotFound can mean that a Process has either already exited, or does not exist. Both IsAlreadyStopped and IsNotExist will currently return true when the error is ErrElementNotFound.

func IsNotSupported 

func IsNotSupported(err error) bool

IsNotSupported returns a boolean indicating whether the error is caused by unsupported platform requests Note: Currently Unsupported platform requests can be mean either ErrVmcomputeInvalidJSON, ErrInvalidData, ErrNotSupported or ErrVmcomputeUnknownMessage is thrown from the Platform

func IsOperationInvalidState 

func IsOperationInvalidState(err error) bool

IsOperationInvalidState returns true when err is caused by `ErrVmcomputeOperationInvalidState`.

func IsPending 

func IsPending(err error) bool

IsPending returns a boolean indicating whether the error is that the requested operation is being completed in the background.

func IsTimeout 

func IsTimeout(err error) bool

IsTimeout returns a boolean indicating whether the error is caused by a timeout waiting for the operation to complete.

func ModifyServiceSettings 

func ModifyServiceSettings(ctx context.Context, settings hcsschema.ModificationRequest) error

ModifyServiceSettings modifies settings of the host compute service.

Types

type ErrorEvent 

type ErrorEvent struct {
	Message    string `json:"Message,omitempty"`    // Fully formated error message
	StackTrace string `json:"StackTrace,omitempty"` // Stack trace in string form
	Provider   string `json:"Provider,omitempty"`
	EventID    uint16 `json:"EventId,omitempty"`
	Flags      uint32 `json:"Flags,omitempty"`
	Source     string `json:"Source,omitempty"`
}

func (*ErrorEvent) String 

func (ev *ErrorEvent) String() string

type HcsError 

type HcsError struct {
	Op     string
	Err    error
	Events []ErrorEvent
}

func (*HcsError) Error 

func (e *HcsError) Error() string

func (*HcsError) Is 

func (e *HcsError) Is(target error) bool

func (*HcsError) Temporary 

func (e *HcsError) Temporary() bool

Deprecated: net.Error.Temporary is deprecated.

func (*HcsError) Timeout 

func (e *HcsError) Timeout() bool

func (*HcsError) Unwrap 

func (e *HcsError) Unwrap() error

type Process 

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

func (*Process) Close 

func (process *Process) Close() (err error)

Close cleans up any state associated with the process but does not kill or wait on it.

func (*Process) CloseStderr 

func (process *Process) CloseStderr(ctx context.Context) (err error)

func (*Process) CloseStdin 

func (process *Process) CloseStdin(ctx context.Context) (err error)

CloseStdin closes the write side of the stdin pipe so that the process is notified on the read side that there is no more data in stdin.

func (*Process) CloseStdout 

func (process *Process) CloseStdout(ctx context.Context) (err error)

func (*Process) ExitCode 

func (process *Process) ExitCode() (int, error)

ExitCode returns the exit code of the process. The process must have already terminated.

func (*Process) Kill 

func (process *Process) Kill(ctx context.Context) (bool, error)

Kill signals the process to terminate but does not wait for it to finish terminating.

func (*Process) Pid 

func (process *Process) Pid() int

Pid returns the process ID of the process within the container.

func (*Process) ResizeConsole 

func (process *Process) ResizeConsole(ctx context.Context, width, height uint16) error

ResizeConsole resizes the console of the process.

func (*Process) Signal 

func (process *Process) Signal(ctx context.Context, options interface{}) (bool, error)

Signal signals the process with `options`.

For LCOW `guestresource.SignalProcessOptionsLCOW`.

For WCOW `guestresource.SignalProcessOptionsWCOW`.

func (*Process) Stdio 

func (process *Process) Stdio() (stdin io.Writer, stdout, stderr io.Reader)

Stdio returns the stdin, stdout, and stderr pipes, respectively. To close them, close the process handle, or use the `CloseStd*` functions.

func (*Process) StdioLegacy 

func (process *Process) StdioLegacy() (_ io.WriteCloser, _ io.ReadCloser, _ io.ReadCloser, err error)

StdioLegacy returns the stdin, stdout, and stderr pipes, respectively. Closing these pipes does not close the underlying pipes. Once returned, these pipes are the responsibility of the caller to close.

func (*Process) SystemID 

func (process *Process) SystemID() string

SystemID returns the ID of the process's compute system.

func (*Process) Wait 

func (process *Process) Wait() error

Wait waits for the process to exit. If the process has already exited returns the previous error (if any).

type ProcessError 

type ProcessError struct {
	HcsError
	SystemID string
	Pid      int
}

ProcessError is an error encountered in HCS during an operation on a Process object

func (*ProcessError) Error 

func (e *ProcessError) Error() string

type System 

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

func CreateComputeSystem 

func CreateComputeSystem(ctx context.Context, id string, hcsDocumentInterface interface{}) (_ *System, err error)

CreateComputeSystem creates a new compute system with the given configuration but does not start it.

func OpenComputeSystem 

func OpenComputeSystem(ctx context.Context, id string) (*System, error)

OpenComputeSystem opens an existing compute system by ID.

func (*System) Close 

func (computeSystem *System) Close() error

Close cleans up any state associated with the compute system but does not terminate or wait for it.

func (*System) CloseCtx 

func (computeSystem *System) CloseCtx(ctx context.Context) (err error)

CloseCtx is similar to System.Close, but accepts a context.

The context is used for all operations, including waits, so timeouts/cancellations may prevent proper system cleanup.

func (*System) CreateProcess 

func (computeSystem *System) CreateProcess(ctx context.Context, c interface{}) (cow.Process, error)

CreateProcess launches a new process within the computeSystem.

func (*System) ExitError 

func (computeSystem *System) ExitError() error

ExitError returns an error describing the reason the compute system terminated.

func (*System) ID 

func (computeSystem *System) ID() string

ID returns the compute system's identifier.

func (*System) IsOCI 

func (computeSystem *System) IsOCI() bool

IsOCI returns whether processes in the compute system should be created via OCI.

func (*System) Modify 

func (computeSystem *System) Modify(ctx context.Context, config interface{}) error

Modify the System by sending a request to HCS

func (*System) OS 

func (computeSystem *System) OS() string

OS returns the operating system of the compute system, "linux" or "windows".

func (*System) OpenProcess 

func (computeSystem *System) OpenProcess(ctx context.Context, pid int) (*Process, error)

OpenProcess gets an interface to an existing process within the computeSystem.

func (*System) Pause 

func (computeSystem *System) Pause(ctx context.Context) (err error)

Pause pauses the execution of the computeSystem. This feature is not enabled in TP5.

func (*System) Properties 

func (computeSystem *System) Properties(ctx context.Context, types ...schema1.PropertyType) (*schema1.ContainerProperties, error)

Properties returns the requested container properties targeting a V1 schema container.

func (*System) PropertiesV2 

func (computeSystem *System) PropertiesV2(ctx context.Context, types ...hcsschema.PropertyType) (_ *hcsschema.Properties, err error)

PropertiesV2 returns the requested compute systems properties targeting a V2 schema compute system.

func (*System) Resume 

func (computeSystem *System) Resume(ctx context.Context) (err error)

Resume resumes the execution of the computeSystem. This feature is not enabled in TP5.

func (*System) Save 

func (computeSystem *System) Save(ctx context.Context, options interface{}) (err error)

Save the compute system

func (*System) Shutdown 

func (computeSystem *System) Shutdown(ctx context.Context) error

Shutdown requests a compute system shutdown.

func (*System) Start 

func (computeSystem *System) Start(ctx context.Context) (err error)

Start synchronously starts the computeSystem.

func (*System) Terminate 

func (computeSystem *System) Terminate(ctx context.Context) error

Terminate requests a compute system terminate.

func (*System) Wait 

func (computeSystem *System) Wait() error

Wait synchronously waits for the compute system to shutdown or terminate. If the compute system has already exited returns the previous error (if any).

func (*System) WaitChannel 

func (computeSystem *System) WaitChannel() <-chan struct{}

func (*System) WaitCtx 

func (computeSystem *System) WaitCtx(ctx context.Context) error

WaitCtx synchronously waits for the compute system to shutdown or terminate, or the context to be cancelled.

See System.Wait for more information.

func (*System) WaitError 

func (computeSystem *System) WaitError() error

type SystemError 

type SystemError struct {
	HcsError
	ID string
}

SystemError is an error encountered in HCS during an operation on a Container object

func (*SystemError) Error 

func (e *SystemError) Error() string

Source Files

callback.go doc.go errors.go process.go service.go system.go utils.go waithelper.go

Directories

PathSynopsis
internal/hcs/resourcepaths
internal/hcs/schema1
internal/hcs/schema2
Version
v0.13.0 (latest)
Published
Apr 21, 2025
Platform
windows/amd64
Imports
29 packages
Last checked
11 hours ago –

Tools for package owners.