exec

Documentation

Overview

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.