package exec

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

Package exec implements a minimalized external process launcher. It exists to work around some shortcomings for Windows scenarios that aren't exposed via the os/exec package.

Index ¶

• type Exec
• func New(path, cmdLine string, opts ...ExecOpts) (*Exec, error)
• func (e *Exec) ExitCode() int
• func (e *Exec) Exited() bool
• func (e *Exec) Kill() error
• func (e *Exec) Pid() int
• func (e *Exec) Run() error
• func (e *Exec) Start() error
• func (e *Exec) Stderr() *os.File
• func (e *Exec) Stdin() *os.File
• func (e *Exec) Stdout() *os.File
• func (e *Exec) Wait() (err error)
• type ExecOpts
• func WithConPty(cpty *conpty.Pty) ExecOpts
• func WithDir(dir string) ExecOpts
• func WithEnv(env []string) ExecOpts
• func WithJobObject(job *jobobject.JobObject) ExecOpts
• func WithProcessFlags(flags uint32) ExecOpts
• func WithStdio(stdout, stderr, stdin bool) ExecOpts
• func WithToken(token windows.Token) ExecOpts

Types ¶

type Exec ¶

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

Exec is an object that represents an external process. A user should NOT initialize one manually and instead should call New() and pass in the relevant options to retrieve one.

The Exec object is not intended to be used across threads and most methods should only be called once per object. It's expected to follow one of two conventions for starting and managing the lifetime of the process.

Either: New() -> e.Start() -> e.Wait() -> (Optional) e.ExitCode()

or: New() -> e.Run() -> (Optional) e.ExitCode()

To capture output or send data to the process, the Stdin(), StdOut() and StdIn() methods can be used.

func New ¶

func New(path, cmdLine string, opts ...ExecOpts) (*Exec, error)

New returns a new instance of an `Exec` object. A process is not running at this point and must be started via either Run(), or a combination of Start() + Wait().

func (*Exec) ExitCode ¶

func (e *Exec) ExitCode() int

ExitCode returns the exit code of the process. If the process hasn't exited, this will return -1.

func (*Exec) Exited ¶

func (e *Exec) Exited() bool

Exited returns if the process has exited.

func (*Exec) Kill ¶

func (e *Exec) Kill() error

Kill will forcefully kill the process.

func (*Exec) Pid ¶

func (e *Exec) Pid() int

Pid returns the pid of the running process. If the process isn't running, this will return -1.

func (*Exec) Run ¶

func (e *Exec) Run() error

Run will run the process to completion. This can be accomplished manually by calling Start + Wait afterwards.

func (*Exec) Start ¶

func (e *Exec) Start() error

Start starts the process with the path and cmdline specified when the Exec object was created. This does not wait for exit or release any resources, a call to Wait must be made afterwards.

func (*Exec) Stderr ¶

func (e *Exec) Stderr() *os.File

Stderr returns the pipe standard error is hooked up to. It's expected that the client will continuously drain the pipe if standard output is requested. This will be closed once Wait returns.

func (*Exec) Stdin ¶

func (e *Exec) Stdin() *os.File

Stdin returns the pipe standard input is hooked up to. This will be closed once Wait returns.

func (*Exec) Stdout ¶

func (e *Exec) Stdout() *os.File

Stdout returns the pipe standard output is hooked up to. It's expected that the client will continuously drain the pipe if standard output is requested. The pipe will be closed once Wait returns.

func (*Exec) Wait ¶

func (e *Exec) Wait() (err error)

Wait synchronously waits for the process to complete and will close the stdio pipes afterwards. This should only be called once per Exec object.

type ExecOpts ¶

type ExecOpts func(e *execConfig) error

func WithConPty ¶

func WithConPty(cpty *conpty.Pty) ExecOpts

WithConPty will launch the created process with a pseudo console attached to the process.

func WithDir ¶

func WithDir(dir string) ExecOpts

WithDir will use `dir` as the working directory for the process.

func WithEnv ¶

func WithEnv(env []string) ExecOpts

WithEnv will use the passed in environment variables for the new process.

func WithJobObject ¶

func WithJobObject(job *jobobject.JobObject) ExecOpts

WithJobObject will launch the newly created process in the passed in job.

func WithProcessFlags ¶

func WithProcessFlags(flags uint32) ExecOpts

WithProcessFlags will pass `flags` to CreateProcess's creationFlags parameter.

func WithStdio ¶

func WithStdio(stdout, stderr, stdin bool) ExecOpts

WithStdio will hook up stdio for the process to a pipe, the other end of which can be retrieved by calling Stdout(), stdErr(), or Stdin() respectively on the Exec object. Stdio will be hooked up to the NUL device otherwise.

func WithToken ¶

func WithToken(token windows.Token) ExecOpts

WithToken will run the process as the user that `token` represents.

Source Files ¶

exec.go options.go