subprocess

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

• func CleanKillOfCommand(ctx context.Context, cmd *exec.Cmd) (err error)
• func ConvertCommandError(err error) error
• func Execute(ctx context.Context, loggers logs.Loggers, messageOnStart string, ...) error
• func ExecuteAs(ctx context.Context, loggers logs.Loggers, messageOnStart string, ...) error
• func ExecuteAsWithEnvironment(ctx context.Context, loggers logs.Loggers, additionalEnvVars []string, ...) (err error)
• func ExecuteWithEnvironment(ctx context.Context, loggers logs.Loggers, additionalEnvVars []string, ...) (err error)
• func ExecuteWithSudo(ctx context.Context, loggers logs.Loggers, messageOnStart string, ...) error
• func Output(ctx context.Context, loggers logs.Loggers, cmd string, args ...string) (string, error)
• func OutputAs(ctx context.Context, loggers logs.Loggers, ...) (string, error)
• func OutputAsWithEnvironment(ctx context.Context, loggers logs.Loggers, additionalEnvVars []string, ...) (output string, err error)
• func OutputWithEnvironment(ctx context.Context, loggers logs.Loggers, additionalEnvVars []string, ...) (string, error)
• type Subprocess
  • func New(ctx context.Context, loggers logs.Loggers, messageOnStart string, ...) (*Subprocess, error)
  • func NewWithEnvironment(ctx context.Context, loggers logs.Loggers, additionalEnvVars []string, ...) (p *Subprocess, err error)
  • func (s *Subprocess) Cancel()
  • func (s *Subprocess) Check() error
  • func (s *Subprocess) Execute() (err error)
  • func (s *Subprocess) IsOn() bool
  • func (s *Subprocess) Restart() (err error)
  • func (s *Subprocess) Setup(ctx context.Context, loggers logs.Loggers, messageOnStart string, ...) (err error)
  • func (s *Subprocess) SetupAs(ctx context.Context, loggers logs.Loggers, messageOnStart string, ...) (err error)
  • func (s *Subprocess) SetupAsWithEnvironment(ctx context.Context, loggers logs.Loggers, additionalEnv []string, ...) (err error)
  • func (s *Subprocess) SetupWithEnvironment(ctx context.Context, loggers logs.Loggers, additionalEnv []string, ...) (err error)
  • func (s *Subprocess) Start() (err error)
  • func (s *Subprocess) Stop() (err error)

Functions

func CleanKillOfCommand

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

func ConvertCommandError

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

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

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 ExecuteWithEnvironment

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 ExecuteWithSudo

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 Output

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

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

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

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 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

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 (*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) 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

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) SetupAsWithEnvironment

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) SetupWithEnvironment

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) 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.