runutil

runutil

A Go utility library for executing external commands and processes with support for piping data between Go native functions and UNIX commands.

Features

• Simple command execution with proper error handling
• Pipeline support for chaining commands like Unix shell pipes
• Custom environments for running commands with specific environment variables
• JSON output parsing for commands that return structured data
• Process inspection (Linux) for querying process state and information
• Process discovery (Linux) for finding processes by name
• Zombie process cleanup for applications that spawn many child processes

Installation

go get github.com/KarpelesLab/runutil

Quick Start

Basic Command Execution

// Run a command with output to stdout
err := runutil.Run("ls", "-la")

// Capture command output as bytes
output, err := runutil.RunGet("date")

// Parse JSON output from a command
var data MyStruct
err := runutil.RunJson(&data, "kubectl", "get", "pods", "-o", "json")

Piping Data

The library excels at creating complex pipelines, mixing Go native methods with external commands:

// Compress data using gzip
compressed, err := runutil.RunPipe(input, "gzip", "-9")
if err != nil {
    return err
}
defer compressed.Close()

// Decompress using Go's gzip package
reader, err := gzip.NewReader(compressed)

Reading Command Output

// Read command output as a stream
pipe, err := runutil.RunRead("cat", "/var/log/syslog")
if err != nil {
    return err
}
defer pipe.Close()

// Process the stream
scanner := bufio.NewScanner(pipe)
for scanner.Scan() {
    fmt.Println(scanner.Text())
}

Custom Environments

// Create a custom environment
env := runutil.NewEnv("/home/myuser", "MY_VAR=value", "DEBUG=true")

// Run command with custom environment
err := env.Run("my-command", "--flag")

// All Run* functions are available as methods on Env
output, err := env.RunGet("printenv", "MY_VAR")

Environment Manipulation

env := runutil.NewEnv("/home/user")

// Set or update a variable
env.Set("DATABASE_URL", "postgres://localhost/mydb")

// Get a variable
value := env.Get("PATH")

// Check if a variable exists
if env.Contains("DEBUG") {
    // ...
}

// Remove a variable
env.Unset("TEMP_VAR")

// Merge environments
combined := env.Join(otherEnv).Dedup()

Shell Commands (Unix only)

// Execute a shell command
err := runutil.Sh("echo 'Hello' | grep -o 'H.*'")

// Safely quote user input for shell commands
userInput := "file with 'quotes' and spaces"
cmd := "cat " + runutil.ShQuote(userInput)
err := runutil.Sh(cmd)

Process Inspection (Linux only)

// Get process state by PID
state, err := runutil.PidState(1234)
if err != nil {
    return err
}

if state.IsRunning() {
    started, err := state.Started()
    fmt.Printf("Process started at: %v\n", started)
}

// Get detailed Linux process info
linuxState, err := runutil.LinuxPidState(1234)
fmt.Printf("Process %s has %d threads\n", linuxState.Comm, linuxState.NumThreads)

Process Discovery (Linux only)

// Find all PIDs for a process name
pids := runutil.PidOf("nginx")
for _, pid := range pids {
    fmt.Printf("Found nginx with PID: %d\n", pid)
}

// Get command-line arguments of a process
args, err := runutil.ArgsOf(pids[0])
fmt.Printf("nginx args: %v\n", args)

Zombie Process Cleanup

// Clean up zombie child processes
// Useful when running as PID 1 or spawning many short-lived processes
err := runutil.Reap()

Error Handling

Unlike standard os/exec, runutil properly propagates errors from commands through pipes. If a command in a pipeline fails, the error is returned when reading from the pipe at EOF:

pipe, _ := runutil.RunPipe(input, "nonexistent-command")
defer pipe.Close()

// The error from the failed command will be returned here
_, err := io.ReadAll(pipe)
if err != nil {
    // err contains the command's exit error
}

Resource Management

When using RunRead or RunPipe, always close the returned Pipe to prevent zombie processes:

pipe, err := runutil.RunRead("long-running-command")
if err != nil {
    return err
}
defer pipe.Close() // Always close!

// Process data...

For graceful shutdown with a timeout:

ctx, cancel := context.WithTimeout(context.Background(), 5*time.Second)
defer cancel()

err := pipe.CloseWait(ctx) // Waits up to 5 seconds, then kills

Troubleshooting

Zombie Processes

If you see zombie processes accumulating, it means Wait() was not called on child processes. This can happen if:

1. You didn't close a Pipe returned by RunRead or RunPipe
2. You didn't read the pipe to EOF

Solutions:

• Always use defer pipe.Close() after getting a Pipe
• Read the pipe completely to EOF
• Call Reap() periodically if running many short-lived commands

Process Not Found

On non-Linux systems, PidOf, ArgsOf, and PidState return empty results or ErrNotSupported. These functions rely on the /proc filesystem which is Linux-specific.

Platform Support

License

MIT License - see LICENSE file for details.