subprocess

package
v1.123.0 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Sep 11, 2025 License: Apache-2.0 Imports: 18 Imported by: 0

Documentation

Overview

Package subprocess allows you to spawn new processes, log their output/error and obtain their return codes.

  • Copyright (C) 2020-2022 Arm Limited or its affiliates and Contributors. All rights reserved.

  • SPDX-License-Identifier: Apache-2.0

  • Copyright (C) 2020-2022 Arm Limited or its affiliates and Contributors. All rights reserved.

  • SPDX-License-Identifier: Apache-2.0

Index

Constants

This section is empty.

Variables

This section is empty.

Functions

func CleanKillOfCommand added in v1.62.0 

func CleanKillOfCommand(ctx context.Context, cmd *exec.Cmd) (err error)

CleanKillOfCommand tries to terminate a command gracefully.

func ConvertCommandError added in v1.62.0 

func ConvertCommandError(err error) error

func Execute 

func Execute(ctx context.Context, loggers logs.Loggers, messageOnStart string, messageOnSuccess, messageOnFailure string, cmd string, args ...string) error

Execute executes a command (i.e. spawns a subprocess).

func ExecuteAs added in v1.48.0 

func ExecuteAs(ctx context.Context, loggers logs.Loggers, messageOnStart string, messageOnSuccess, messageOnFailure string, as *commandUtils.CommandAsDifferentUser, cmd string, args ...string) error

ExecuteAs executes a command (i.e. spawns a subprocess) as a different user.

func ExecuteAsWithEnvironment added in v1.60.0 

func ExecuteAsWithEnvironment(ctx context.Context, loggers logs.Loggers, additionalEnvVars []string, messageOnStart string, messageOnSuccess, messageOnFailure string, as *commandUtils.CommandAsDifferentUser, cmd string, args ...string) (err error)

ExecuteAsWithEnvironment executes a command (i.e. spawns a subprocess) as a different user. It allows to specify the environment the subprocess should use. Each entry is of the form "key=value".

func ExecuteAsWithEnvironmentWithIO added in v1.123.0 

func ExecuteAsWithEnvironmentWithIO(ctx context.Context, loggers logs.Loggers, io ICommandIO, additionalEnvVars []string, messageOnStart string, messageOnSuccess, messageOnFailure string, as *commandUtils.CommandAsDifferentUser, cmd string, args ...string) (err error)

ExecuteAsWithEnvironmentWithIO executes a command (i.e. spawns a subprocess) as a different user with overridden stdin/stdout/stderr. It allows to specify the environment the subprocess should use. Each entry is of the form "key=value".

func ExecuteAsWithIO added in v1.123.0 

func ExecuteAsWithIO(ctx context.Context, loggers logs.Loggers, io ICommandIO, messageOnStart string, messageOnSuccess, messageOnFailure string, as *commandUtils.CommandAsDifferentUser, cmd string, args ...string) error

ExecuteAsWithIO executes a command (i.e. spawns a subprocess) as a different user with overridden stdin/stdout/stderr.

func ExecuteWithEnvironment added in v1.60.0 

func ExecuteWithEnvironment(ctx context.Context, loggers logs.Loggers, additionalEnvVars []string, messageOnStart string, messageOnSuccess, messageOnFailure string, cmd string, args ...string) (err error)

ExecuteWithEnvironment executes a command (i.e. spawns a subprocess). It allows to specify the environment the subprocess should use. Each entry is of the form "key=value".

func ExecuteWithEnvironmentWithIO added in v1.123.0 

func ExecuteWithEnvironmentWithIO(ctx context.Context, loggers logs.Loggers, io ICommandIO, additionalEnvVars []string, messageOnStart string, messageOnSuccess, messageOnFailure string, cmd string, args ...string) (err error)

ExecuteWithEnvironment executes a command (i.e. spawns a subprocess) with overridden stdin/stdout/stderr. It allows to specify the environment the subprocess should use. Each entry is of the form "key=value".

func ExecuteWithIO added in v1.123.0 

func ExecuteWithIO(ctx context.Context, loggers logs.Loggers, io ICommandIO, messageOnStart string, messageOnSuccess, messageOnFailure string, cmd string, args ...string) error

ExecuteWithIO executes a command (i.e. spawns a subprocess) with overridden stdin/stdout/stderr.

func ExecuteWithSudo added in v1.48.0 

func ExecuteWithSudo(ctx context.Context, loggers logs.Loggers, messageOnStart string, messageOnSuccess, messageOnFailure string, cmd string, args ...string) error

ExecuteWithSudo executes a command (i.e. spawns a subprocess) as root.

func ExecuteWithSudoWithIO added in v1.123.0 

func ExecuteWithSudoWithIO(ctx context.Context, loggers logs.Loggers, io ICommandIO, messageOnStart string, messageOnSuccess, messageOnFailure string, cmd string, args ...string) error

ExecuteWithSudoWithIO executes a command (i.e. spawns a subprocess) as root with overridden stdin/stdout/stderr.

func Output added in v1.47.0 

func Output(ctx context.Context, loggers logs.Loggers, cmd string, args ...string) (string, error)

Output executes a command and returns its output (stdOutput and stdErr are merged) as string.

func OutputAs added in v1.48.0 

func OutputAs(ctx context.Context, loggers logs.Loggers, as *commandUtils.CommandAsDifferentUser, cmd string, args ...string) (string, error)

OutputAs executes a command as a different user and returns its output (stdOutput and stdErr are merged) as string.

func OutputAsWithEnvironment added in v1.60.0 

func OutputAsWithEnvironment(ctx context.Context, loggers logs.Loggers, additionalEnvVars []string, as *commandUtils.CommandAsDifferentUser, cmd string, args ...string) (output string, err error)

OutputAsWithEnvironment executes a command as a different user and returns its output (stdOutput and stdErr are merged) as string. It allows to specify the environment the subprocess should use. Each entry is of the form "key=value".

func OutputWithEnvironment added in v1.60.0 

func OutputWithEnvironment(ctx context.Context, loggers logs.Loggers, additionalEnvVars []string, cmd string, args ...string) (string, error)

OutputWithEnvironment executes a command and returns its output (stdOutput and stdErr are merged) as string. It allows to specify the environment the subprocess should use. Each entry is of the form "key=value".

Types

type ICommandIO added in v1.123.0 

type ICommandIO interface {
	// Register creates new readers and writers based on the constructor methods in the ICommandIO implementation. If the constructors are not specified then it will default to os.Stdin, os.Stdout, and os.Stderr
	Register(context.Context) (in io.Reader, out, errs io.Writer)
}

ICommandIO allows you to set the stdin, stdout, and stderr that will be used in a subprocess. A context can be injected for context aware readers and writers

func NewDefaultIO added in v1.123.0 

func NewDefaultIO() ICommandIO

func NewIO added in v1.123.0 

func NewIO(
	newInFunc func(context.Context) io.Reader,
	newOutFunc func(context.Context) io.Writer,
	newErrorFunc func(context.Context) io.Writer,
) ICommandIO

func NewIOFromLoggers added in v1.123.0 

func NewIOFromLoggers(loggers logs.Loggers) ICommandIO

type Subprocess 

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

Subprocess describes what a subprocess is as well as any monitoring it may need.

func New 

func New(ctx context.Context, loggers logs.Loggers, messageOnStart string, messageOnSuccess, messageOnFailure string, cmd string, args ...string) (*Subprocess, error)

New creates a subprocess description.

func NewWithEnvironment added in v1.60.0 

func NewWithEnvironment(ctx context.Context, loggers logs.Loggers, additionalEnvVars []string, messageOnStart string, messageOnSuccess, messageOnFailure string, cmd string, args ...string) (p *Subprocess, err error)

NewWithEnvironment creates a subprocess description. It allows to specify the environment the subprocess should use. Each entry is of the form "key=value".

func NewWithEnvironmentWithIO added in v1.123.0 

func NewWithEnvironmentWithIO(ctx context.Context, loggers logs.Loggers, io ICommandIO, additionalEnvVars []string, messageOnStart string, messageOnSuccess, messageOnFailure string, cmd string, args ...string) (p *Subprocess, err error)

NewWithEnvironmentWithIO creates a subprocess description with overridden stdin/stdout/stderr. It allows to specify the environment the subprocess should use. Each entry is of the form "key=value".

func NewWithIO added in v1.123.0 

func NewWithIO(ctx context.Context, loggers logs.Loggers, io ICommandIO, messageOnStart string, messageOnSuccess, messageOnFailure string, cmd string, args ...string) (*Subprocess, error)

NewWithIO creates a subprocess description with overridden stdin/stdout/stderr.

func (*Subprocess) Cancel 

func (s *Subprocess) Cancel()

Cancel interrupts an ongoing process. This method is idempotent.

func (*Subprocess) Check 

func (s *Subprocess) Check() error

Check checks whether the subprocess is correctly defined.

func (*Subprocess) Execute 

func (s *Subprocess) Execute() (err error)

Execute executes the command and waits for completion.

func (*Subprocess) Interrupt added in v1.100.0 

func (s *Subprocess) Interrupt(ctx context.Context) (err error)

Interrupt terminates the process This method should be used in combination with `Start`. This method is idempotent

func (*Subprocess) IsOn 

func (s *Subprocess) IsOn() bool

IsOn states whether the subprocess is running or not.

func (*Subprocess) Restart 

func (s *Subprocess) Restart() (err error)

Restart restarts a process. It will stop the process if currently running.

func (*Subprocess) Setup 

func (s *Subprocess) Setup(ctx context.Context, loggers logs.Loggers, messageOnStart string, messageOnSuccess, messageOnFailure string, cmd string, args ...string) (err error)

Setup sets up a sub-process i.e. defines the command cmd and the messages on start, success and failure.

func (*Subprocess) SetupAs added in v1.48.0 

func (s *Subprocess) SetupAs(ctx context.Context, loggers logs.Loggers, messageOnStart string, messageOnSuccess, messageOnFailure string, as *commandUtils.CommandAsDifferentUser, cmd string, args ...string) (err error)

SetupAs is similar to Setup but allows the command to be run as a different user.

func (*Subprocess) SetupAsWithCustomIO added in v1.123.0 

func (s *Subprocess) SetupAsWithCustomIO(ctx context.Context, loggers logs.Loggers, io ICommandIO, messageOnStart string, messageOnSuccess, messageOnFailure string, as *commandUtils.CommandAsDifferentUser, cmd string, args ...string) (err error)

SetupAsWithCustomIO is similar to SetupWithCustomIO but allows the command to be run as a different user. It allows the stdin, stdout, and stderr to be overridden.

func (*Subprocess) SetupAsWithEnvironment added in v1.60.0 

func (s *Subprocess) SetupAsWithEnvironment(ctx context.Context, loggers logs.Loggers, additionalEnv []string, messageOnStart string, messageOnSuccess, messageOnFailure string, as *commandUtils.CommandAsDifferentUser, cmd string, args ...string) (err error)

SetupAsWithEnvironment is similar to Setup but allows the command to be run as a different user. Compared to SetupAs, it allows specifying additional environment variables to be used by the process.

func (*Subprocess) SetupAsWithEnvironmentWithCustomIO added in v1.123.0 

func (s *Subprocess) SetupAsWithEnvironmentWithCustomIO(ctx context.Context, loggers logs.Loggers, io ICommandIO, additionalEnv []string, messageOnStart string, messageOnSuccess, messageOnFailure string, as *commandUtils.CommandAsDifferentUser, cmd string, args ...string) (err error)

SetupAsWithEnvironmentWithCustomIO is similar to SetupWithCustomIO but allows the command to be run as a different user. Compared to SetupAsWithCustomIO, it allows specifying additional environment variables to be used by the process. It allows the stdin, stdout, and stderr to be overridden.

func (*Subprocess) SetupWithCustomIO added in v1.123.0 

func (s *Subprocess) SetupWithCustomIO(ctx context.Context, loggers logs.Loggers, io ICommandIO, messageOnStart string, messageOnSuccess, messageOnFailure string, cmd string, args ...string) (err error)

SetupWithCustomIO sets up a sub-process i.e. defines the command cmd and the messages on start, success and failure. It allows the stdin, stdout, and stderr to be overridden.

func (*Subprocess) SetupWithEnvironment added in v1.60.0 

func (s *Subprocess) SetupWithEnvironment(ctx context.Context, loggers logs.Loggers, additionalEnv []string, messageOnStart string, messageOnSuccess, messageOnFailure string, cmd string, args ...string) (err error)

SetupWithEnvironment sets up a sub-process i.e. defines the command cmd and the messages on start, success and failure. Compared to Setup, it allows specifying additional environment variables to be used by the process.

func (*Subprocess) SetupWithEnvironmentWithCustomIO added in v1.123.0 

func (s *Subprocess) SetupWithEnvironmentWithCustomIO(ctx context.Context, loggers logs.Loggers, io ICommandIO, additionalEnv []string, messageOnStart string, messageOnSuccess, messageOnFailure string, cmd string, args ...string) (err error)

SetupWithEnvironmentWithCustomIO sets up a sub-process i.e. defines the command cmd and the messages on start, success and failure. Compared to SetupWithCustomIO, it allows specifying additional environment variables to be used by the process. It allows the stdin, stdout, and stderr to be overridden.

func (*Subprocess) Start 

func (s *Subprocess) Start() (err error)

Start starts the process if not already started. This method is idempotent.

func (*Subprocess) Stop 

func (s *Subprocess) Stop() (err error)

Stop stops the process straight away if currently working without waiting for completion. This method should be used in combination with `Start`. However, in order to interrupt a process however it was started (using `Start` or `Execute`), prefer `Cancel`. This method is idempotent.

func (*Subprocess) Wait added in v1.100.0 

func (s *Subprocess) Wait(ctx context.Context) (err error)

Wait waits for the command to stop existing on the system. This allows check to work if the underlying process was stopped.

Source Files

View all Source files

Directories

Path Synopsis

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.